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从 前 打 心 眼 儿 里 讨厌 编译 成 JavaScript 的 这 类 语言 ， 像 Coffee，Dart 等 。 但 是 
在 15 年 春节 前 后 却 爱 上 了 TypeScript。 同时 非常 喜欢 的 框架 Dojo ，Angularjs 也 
宣布 使 用 TypeScript 做 新 版 本 的 开发 。 那 么 TypeScript 完 竟 为 何 物 2 又 有 什么 
魅力 呢 ? 


TypeScript 是 Microsoft 公 司 注 册 商标 。 


TypeScript 具 有 类 型 系统 ， 且 是 JavaScript 的 超 集 。 它 可 以 编译 成 普通 的 JavaScript 
代码 。 TypeScript 支 持 任 意 浏 览 器 ， 任 意 环境 ， 任 意 系统 并 且 是 开源 的 。 


TypeScript 目 前 还 在 积极 的 开发 完善 之 中 ， 不 断 地 会 有 新 的 特性 加 入 进来 。 因此 本 
手册 也 会 紧 随 官方 的 每 个 commit， 不 断 地 更 新 新 的 章节 以 及 修改 措 词 不 受 之 处 。 


如 果 你 对 TypeScript 一 见 钟情 ， 可 以 订阅 ang-staf 本 手册 ， 及 时 了 解 ECMAScript 
2015 以 及 2016 里 新 的 原生 特性 ， 并 借助 TypeScript 提 前 掌握 使 用 它们 的 方式 ! 如 
果 你 对 TypeScript 的 爱 愈 发 浓烈 ， 可 以 与 楼 主 一 起 边 翻 译 边 学 习 ，PRSs Welcome!!! 
在 相关 链接 的 末尾 可 以 找到 本 手册 的 Github 地 址 。 
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让 我 们 使 用 TypeScript 来 创建 一 个 简单 的 Web 应 用 。 


安装 TypeScript 
有 两 种 主要 的 方式 来 获取 TypeScript 工 具 : 


e 通过 npm (Node.js 包 管理 器 ) 
e 安装 Visual Studio 的 TypeScript 插 件 


Visual Studio 2017 和 Visual Studio 2015 Update 3 默认 包含 了 TypeScript。 如 果 你 
的 Visual Studio 还 没有 安装 TypeScript， 你 可 以 下 载 它 。 


针对 使 用 npm 的 用 户 : 


> npm install -g typescript 


构建 你 的 第 一 个 TypeScript 文 件 


在 编辑 器 ， 将 下 面 的 代码 输入 到 greeter .ts 文件 里 : 


function greeter(person) { 
return "Hello, " + person; 

} 

let user = "Jane User"; 


document.body.innerHTML = greeter(user); 


编译 代码 


我 们 使 用 了 .ts 扩展 名 ， 但 是 这 段 代码 仅仅 是 JavaScript 而 已 。 你 可 以 直接 从 现 
有 的 JavaScript 应 用 里 复制 /粘贴 这 段 代 码 。 


ix 
在 命令 行 上 ， 运 行 TypeScript 编 译 器 : 


tsc greeter.ts 


输出 结果 为 一 个 greeter.js 文件 ， 它 包含 了 和 输入 文件 中 相同 的 JavsScript 代 
码 。 一 切 准 备 就 绪 ， 我 们 可 以 运行 这 个 使 用 TypeScript 写 的 JavaScript 应 用 了 ! 


接 下 来 让 我 们 看 看 TypeScript 工 具 带 来 的 高 级 功能 。 给 person 函数 的 参数 添加 : 
string 类 型 注解 ， 如 下 : 


function greeter(person: string) { 
return "Hello, " + person; 
let user = "Jane User"; 


document.body.innerHTML = greeter(user); 


类 型 注解 
TypeScript 里 的 类 型 注解 是 一 种 轻 量 级 的 为 函数 或 变量 添加 约束 的 方式 。 在 这 个 例 
子 里 ， 我 们 希望 greeter 函数 接收 一 个 字符 串 参 数 。 然后 尝试 把 greeter 的 调 


用 改 成 传 入 一 个 数组 : 


function greeter(person: string) { 
return "Hello, " + person; 


let user = [0, 1, 2]; 


document.body.innerHTML = greeter(user); 


重新 编译 ， 你 会 看 到 产生 了 一 个 错误 。 


error TS2345: Argument of type 'number[]' is not assignable to p 
arameter of type 'string'. 


类 似 地 ， 尝 试 删除 greeter 调用 的 所 有 参数 。 TypeScript 会 告诉 你 使 用 了 非 期 望 
个 数 的 参数 调用 了 这 个 函数 。 在 这 两 种 情况 中 ，TypeScript 提 供 了 静态 的 代码 分 
析 ， 它 可 以 分 析 代 码 结构 和 提供 的 类 型 注解 。 


要 注意 的 是 尽管 有 错误 ， greeter.js 文件 还 是 被 创建 了 。 就 算 你 的 代码 里 有 错 
误 ， 你 仍然 可 以 使 用 TypeScript。 但 在 这 种 情况 下 ，TypeScript 会 警告 你 代码 可 能 
不 会 按 预 期 执行 。 


接口 


让 我 们 开发 这 个 示例 应 用 。 这 里 我 们 使 用 接口 来 描述 一 个 拥 

有 firstName 和 lastName 字段 的 对 象 。 在 TypeScript 里 ， 只 在 两 个 类 型 内 部 的 
结构 兼容 那么 这 两 个 类 型 就 是 兼容 的 。 这 就 允许 我 们 在 实现 接口 时 候 只 要 保证 包含 
了 接口 要 求 的 结构 就 可 以 ， 而 不 必 明 确 地 使 用 implements 744 ° 


interface Person { 
firstName: string; 
lastName: string; 


function greeter(person: Person) { 
return "Hello, " + person.firstName + " " + person. lastName; 


let user = { firstName: "Jane", lastName: "User" }; 


document.body.innerHTML = greeter(user); 


X 


最 后 ， 证 我 们 使 用 类 来 改写 这 个 例子 。 TypeScript X44 JavaScripts 3t AF tE > rete 
支持 基于 类 的 面向 对 象 编程 。 


让 我 们 创建 一 个 Student 类 ， 它 带 有 一 个 构造 了 兄 数 和 一 些 公共 字段 。 注意 类 和 接 
口 可 以 一 起 共 作 ， 程 序 员 可 以 自行 决定 抽象 的 级 别 。 


还 要 注意 的 是 ， 在 构造 函数 的 参数 上 使 用 public 等 同 于 创建 了 同名 的 成 员 变 量 。 


class Student { 
fullName: string; 
constructor(public firstName: string, public middleInitial: 
string, public lastName: string) { 
this.fullName = firstName + " " + middleInitial + " " + 
lastName; 


j 


interface Person { 
firstName: string; 
lastName: string; 


function greeter(person : Person) 1 
return "Hello, " + person.firstName + " " + person. lastName; 


let user - new Student("Jane", "M.", "User"); 


document.body.innerHTML = greeter(user); 


重新 运行 tsc greeter.ts ， 你 会 看 到 生成 的 JavaScript 代 码 和 原先 的 一 样 。 
TypeScript 里 的 类 只 是 JavaScript 里 常用 的 基于 原型 面向 对 象 编程 的 简写 。 


运行 TypeScript Web 应 用 
在 greeter.html 里 输入 如 下 内 容 : 


<!DOCTYPE html> 


<html> 
<head><title>TypeScript Greeter</title></head> 
<body> 
«script src="greeter.js"></script> 
</body> 


</html> 


在 浏览 器 里 打开 greeter.html 运行 这 个 应 用 | 


可 选 地 : 在 Visual Studio 里 打开 greeter.ts 或 者 把 代码 复制 到 TypeScript 
playground » 将 鼠标 悬 停 在 标识 符 上 查看 它们 的 类 型 。 注意 在 某 些 情况 下 它们 的 
类 型 可 以 被 自动 地 推断 出 来 。 重新 输入 一 下 最 后 一 行 代码 ， 看 一 下 自动 补 全 列表 和 
参数 列表 ， 它 们 会 根据 DOM 元 素 类 型 而 变化 。 将 光标 放 在 greeter 函数 上 ， 点 
击 F12 可 以 跟踪 到 它 的 定义 。 还 有 一 点 ， 你 可 以 右键 点 击 标 识 ， 使 用 重 构 功 能 来 重 


这 些 类 型 信息 以 及 工具 可 以 很 好 的 M E EL 。 更 多 的 TypeScript 功 能 
> 请 查看 本 网 站 的 示例 部 分 


ASP.NET Core 


安装 ASP.NET Core 和 TypeScript 


首先 ， 若 有 需要 请 安装 ASPNET Core。 此 篇 指南 需要 使 用 Visual Studio 2015 X 
2017 ° 


其 次 ， 如 果 你 的 Visual Studio 不 带 有 最 新 版 本 的 TypeScript， 你 可 以 从 这 里 安装 。 


新 建 工程 


. 选择 File 
. 选择 New Project (Ctrl + Shift + N ) 
. 选择 Visual C# 


. 若 使 用 VS2015， 选 择 ASP.NET Web Application > ASP.NET 5 Empty， 并 
且 取 消 色 选 “Host in the cloud”， 因 为 我 们 要 在 本 地 运行 。 


KR O N > 





New ASP.NET Project - WebApplication10 





? x 
Select a template: 
An empty project template for creating an ASP.NET 5 
ASP.NET 4.5.2 Templates application. This template does not have any content in 
it. 
=, = 4 4 
e-1 e-1 =i el Tem] Learn more 
Empty Web Forms MVC Web API Single Page 
Application 
4 c? 
= 
m e] 
Azure API App Azure Mobile 
(Preview) Service 
ASP.NET 5 Templates 
=, 5 5 
el m Cd 
change Authentication 
Empty Web API Web Zack petals 





Application 
Authentication: No Authentication 


Add folders and core references for: © Microsoft Azure 


WebForms [| MVC | | WebAPI (a) 











Host in the cloud 





Web App 
Add unit tests 


Test project name: | WebApplication10.Tests 








OK Cancel 














5. 若 使 用 VS2017， 选 择 ASP.NET Core Web Application (.NET Core) > 


ASP.NET Core 1.1 Empty 。 





New ASP.NET Core Web Application (.NET Core) - WebApplication10 


ASP.NET Core 1.1 Templates 


N A 一 


Empty Web API Web 
Application 





运行 此 应 用 以 确保 它 能 正常 工作 。 


VS2015 


在 project.json 文件 的 "dependencies" 


"Microsoft.AspNet.StaticFiles": 


An empty project template for creating an ASP.NET 
Core application. This template does not have any 
content in it. 


Learn more 





Change Authentication 


Authentication: No Authentication 








字段 里 添加 : 


"1.0.0-rce1-final" 


最 终 的 dependencies 部 分 应 该 类 似 于 下 面 这 样 : 


"dependencies": { 


"Microsoft.AspNet.IISPlatformHandler": 
"150.0-6rcistinal" 
1:0:70-rcT-f1n8gd 


"Microsoft.AspNet.Server.Kestrel": 
"Microsoft.AspNet.StaticFiles": 
ty 


"1.0.0-rc1-final", 





用 以 下 内 容 替 换 Startup.cs 文件 里 的 Configure HX: 


public void Configure(IApplicationBuilder app) 
{ 
app.UselISPlatformHandler(); 
app.UseDefaultFiles(); 
app.UseStaticFiles(); 


VS2017 


打开 Dependencies > Manage NuGet Packages > Browse ° 1€ X #- 


J+ 


% Microsoft.AspNetCore.StaticFiles 1.1.2: 


24) WebApplication1 - Microsoft Visual Studio ta É | Quick Launch (Ctrl Q) Ld oc c X 
File Edit View Project Build Debug Team Tools Test Analyze Window Help Limin zhu ~ 图 
SR t- a C -| Debug ~| Any cru > P iisexpress~ È 7| P. 


NuGet WebApplication’ = X WebApplication1 


uia 名 -| 了 下- [rJ - 
Browse Installed Updates NuGet Package Manager: WebApplication1 $8-|o-soB|» 


Search Solution Explorer (Ctrl+;) p- 





Microsoft AspNetCore.StaticFiles 








Include prerelease 





packs source: [ugevorg E fal Solution 'WebApplication1' (1 project) 


4 E] WebApplication1 
Microsoft.AspNetCore StaticFiles M eee aes 


" = Dependencies 
Microsoft.AspNetCore.StaticFiles by Microsoft, 4.02M downloads Add Reference... — 


ASP.NET Core static files middleware. Includes middleware for serving static files, directory browsing, and default 


fb Add Connected Service... 
files Version: Latest stable 1.1.2 人 
Microsoft.AspNetCore.StaticFilesEx by Microsoft AspNetCore.StaticFilesEx, 1.59K downloads 


ASP.NET Core static files middleware. Includes middleware for serving static files, directory browsing, and default ©) Options EP New Solution Explorer View 
files, 


Scope to This 





Description 

ASP.NET Core static files middleware. Includes middleware for serving 
static files, directory browsing, and default files. 

Version: 112 

Author(s): Microsoft 


License: http://www.microsoft.com/web/webpi/eula/ 
net library eula enu.htm 


Date published: Tuesday, May 9, 2017 (5/9/2017) 


Error List ... 


Entire Solution -| A O Wemings || @ o Messages | *r| Build + inteliseme — - 


" Code Description 

















Search Error List 





Project Line Suppression S... 


LUTTE Error List... OWENS 





M Add to Source Control = 


如 下 替换 掉 Startup.cs € Configure NAR: 


public void Configure(IApplicationBuilder app) 
t 
app.UseDefaultFiles(); 
app.UseStaticFiles(); 





ASP.NET Core 


Asha TypeScript 


下 一 步 我 们 为 TypeScript 添加 一 个 文件 夹 。 






Application5\Project_Readme.html 


‘ation 


DEPLOY GE 





IC Ensure your app is ready for 





| Area... 
iu 
"cp Existing Item... 


Ctrl+Shift+A 
Shift+Alt+A 


New Item... 





affolded Item... 





Azure API App SDK... 
Azure API App Client... 

^ New Azure WebJob Project 
Existing Project as Azure WebJob 
Reference... 

| Service Reference... 


| % Connected Service... 


Analyzer... 
TypeScript File 
TypeScript JSX File 
HTML Page 
JavaScript File 
Style Sheet 
Web Form 

| ts Class... 








将 文件 夹 命名 为 scripts 。 


oo By 


BE 


Bx 


bh Build 


Rebuild 

Clean 

View 

Analyze 

Convert 

Publish... 

Configure Azure AD Authentication... 
Add Application Insights Telemetry... 
Scope to This 

New Solution Explorer View 
Show on Code Map 

Add 

Manage NuGet Packages... 

Set as StartUp Project 

Debug 

Initialize Interactive with Project 
Source Control 

Cut 

Paste 

Remove 

Rename 

Unload Project 

Open Folder in File Explorer 


Properties 






日 日 省 | 四 -与 
Search Solution Explorer (Ctrl+;) 






网 Solution 'WebApplication5' (1 project) 


operties 
eferences 

pp_Data 

pp_Start 

ontent 

ontrollers 

> jnts 

odels 

Fripts 

ews 

vicon.ico 

obal.asax 
ackages.config 
roject Readme.html 





artup.cs 

* feb.config 
» 
» 

Ctrl+X 

Ctrl+V 

Del 

Alt+Enter 
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Solution Explorer 


2@\o-sapls= 


Search Solution Explorer (Ctrl+;) 











网 Solution 'WebApplication10' (1 project) 
4 | Solution Items 
£T global.json 
4 src 
4 [5] WebApplication10 
b £ Properties 
References 


qulpfile.js 
£T package,json 
b £T projectjson 
L3) Project Readme.html 
c* Startup.cs 
4 KK] TypeScript Virtual Projects 
4 [Ñ scripts (tsconfig project) 
RAR lib.d.ts 
() tsconfig.json 
2^ app.ts 





添加 TypeScript 代码 


在 scripts 上 右 击 并 选择 New Item 。 接着 选择 TypeScript File (也 可 能 .NET 
Core 部 分 ) ， 并 将 此 文件 命名 为 app.ts » 








Add New Item - WebApplication5 ? x 





4 Installed Sort by: Default H TE :三 Search Installed Templates (Ctrl+ 日 PpP- 
4 Visual CË HTML Page g JSON Schema File Type: Visual C# 
Code 5 : 
Data JavaScript File £T JSXFile A blank TypeScript source file 
General Style Sheet mi) LESS Style Sheet 
um Web Form MVC 5 Layout Page (Razor) 
General 
Markup Web Form with Master Page MVC 5 Partial Page (Razor) 
MVC MVC 5 View Page (Razor) JA OWIN Startup class 
Razor 
Scripts MVC 5 View Page with Layout (Razor) si SCSS Style Sheet (SASS) 
SignalR Web API Controller Class (v2.1) & Site Map 
— SignalR Hub Class (v2 ] TypeScript File 
Wsb/Fomis igna u ass (v2) ypeScript File 
Windows Forms SignalR Persistent Connection Class... £  TypeScript JSON Configuration File 
WPF ASP.NET Handler 国 TypeScript JSX File 
b Cross-Platform 
Reporting ASP.NET Module & WCF Data Service 5.6.4 
Silverlight Browser File @ WCF Service 
SQL Server 
Workflow CoffeeScript File @ WCF Service (Ajax-enabled) 
PowerShell Dynamic Data Field y Web Configuration File 
b Online Generic Handler Web Forms Master Page 
JSON File Web Forms Master Page (Nested) 
4 > 
Click here to go online and find templates. 
Name: app.ts 








添加 示例 代码 
将 以 下 代码 写 入 app.ts 文 件 。 


function sayHello() { 

const compiler = (document.getElementById("compiler") as HTMLI 
nputElement).value; 

const framework = (document.getElementById("framework") as HTM 
LInputElement).value; 

return “Hello from ${compiler} and ${framework}!°; 


构建 设置 


配置 TypeScript A14 4 


我 们 先 来 告诉 TypeScript 怎 样 构 建 。 右 击 Scripts 文 件 夹 并 选择 New Item 。 接着 选 
择 TypeScript Configuration File， 保 持 文件 的 默认 名 字 为 tsconfig.json ° 


ASP.NET Core 














Add New Item - WebApplication3 ? x 
4 Installed Sort by: Default -ii Search Installed Templates (Ctrl+ 日 »- 
4 Visual C$ HTML Page £T JSON Schema File Type: Visual C 
Code JavaScript File ST JsxFile JSON configuration file for the TypeScript 
Data compiler 
General Style Sheet mi) LESS Style Sheet 
“ Ws Web Form MVC 5 Layout Page (Razor) 
General 
Markup Web Form with Master Page [] MVC 5 Partial Page (Razor) 
MVC MVC 5 View Page (Razor) JA OWIN Startup class 
Razor 
Scripts MVC 5 View Page with Layout (Razor) SCSS Style Sheet (SASS) 
SignalR Web API Controller Class (v2.1) i Site Map 
€— SignalR Hub Class (v2) B TypeScript Fil 
Web Forms ignalR Hub Class (v. ypeScript File 
Windows Forms SignalR Persistent Connection Class... PAC ON Configuration File 
WPF ASP.NET Handler Bl TypeScript JSX File 
b Cross-Platform 
Reporting ASP.NET Module & WCF Data Service 5.6.4 
Silverlight Browser File Gb WCF Service 
SQL Server 
Workflow CoffeeScript File Gb WCF Service (Ajax-enabled) 
PowerShell Dynamic Data Field yD Web Configuration File 
> Online Generic Handler Web Forms Master Page 
JSON File Web Forms Master Page (Nested) 
4 > 
Click here to go online and find templates. 
Name: tsconfig.json 








将 上 默认 的 tsconfig.json 内 容 改 为 如 下 所 示 : 


"compilerOptions": { 
"noImplicitAny": true, 
"noEmitOnError": true, 
"sourceMap": true, 
"rarget'- “ess”! 


tr 
"piles 

",/app.ts" 
], 


"compileOnSave": true 


看 起 来 和 默认 的 设置 差不多 ， 但 注意 以 下 不 同 之 处 : 


1. 设置 "noImplicitAny": true ° 
2. 显 式 列 出 了 "files" 而 不 是 依据 "excludes" 。 


3. i& i£ "compileOnSave": true ° 
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当 你 写 新 代码 时 ， 设 置 "noImplicitAny" 选项 是 个 不 错 的 选择 一 这 可 以 确保 你 
不 会 错 写 任 何 新 的 类 型 。 设置 "compileOnSave" 选项 可 以 确保 你 在 运行 Web 程 序 
前 自动 编译 保存 变更 后 的 代码 。 


Ac 2 NPM 


现在 ， 我 们 来 配置 NPM 以 使 用 我 们 能 够 下 载 JavaScript 包 。 在 工程 上 右 击 并 选择 
New Item ° 接着 选择 NPM Configuration File， 保 持 文件 的 默认 名 字 
为 package.json ° Æ "devDependencies" 部 分 添加 "gulp" 和 "del" : 


"devDependencies": { 


woup: Ea MOROL 
"dedos u2 2:05 


保存 这 个 文件 后 ，Visual Studio 将 开始 安装 gulp 和 del。 若 没有 自动 开始 ， 请 右 击 
package.json x #+ i&4#Restore Packages 。 


iX à. gulp 


最 后 ， 添 加 一 个 新 JavaScript 文 件 gulpfile.js 。 键 入 以 下 内 容 : 


/// <binding AfterBuild='default' Clean='clean' /> 

/* 

This file is the main entry point for defining Gulp tasks and us 
ing Gulp plugins. 

Click here to learn more. http://go.microsoft.com/fwlink/?LinkId 
=518007 

oy, 


var gulp = require('gulp'); 
var del = require('del'); 


var paths = { 
Scripts: sem 7 Si SC RIDES) 72/72 poscis >. 
map'], 


}; 


gulp.task('clean', function () { 
return del(['wwwroot/scripts/**/*']); 


3): 


gulp.task('default', function () { 
gulp.src(paths.scripts).pipe(gulp.dest('wwwroot/scripts')) 


}); 
第 一 行 是 告诉 Visual Studio 构 建 完 成 后 ， 立 即 运行 'default' 任 务 。 当 你 应 答 Visual 
Studio 清除 构建 内 容 后 ， 它 也 将 运行 'clean' 任 务 。 


现在 ， 右 击 gulpfile.js 并 选择 Task Runner Explorer ^ ZX'default'fe'clean 4t 
务 没有 显示 输出 内 容 的 话 ， 请 刷新 explorer : 


task Runner Explorer 
f 


gbApplication11 v=] Bindings default x 
$ Gulpfile.js cmd.exe /c gulp -b ' 
4 Tasks 

default 
clean 





在 wwwroot 中 添加 一 个 新 建 项 index.html 。 在 index.html 中 写 入 以 下 代 
码 : 


<!DOCTYPE html» 
«html» 
«head» 
«meta charset="utf-8" /> 
<script src="scripts/app.js"></script> 


litle /lt eS 

</head> 

<body> 
<div id="message"></div> 
<div> 


Compiler: «input id="compiler" value="TypeScript" onkeyup 
="document.getElementById('message').innerText = sayHello()" />< 
br /> 

Framework: <input id="framework" value="ASP.NET" onkeyup= 
"document .getElementById('message').innerText = sayHello()" /> 

</div> 
</body> 
</html> 


i] = 





测 试 


1. 运行 项 目 。 
2. 在 输入 框 中 键入 时 ， 您 应 该 看 到 一 个 消息 : 





Ed Home Page - My ASP.NI X 十 


= =. C) | localhost 





Hello from TypeScript and ASP.NET! 
Compiler: [TypeScript 
Framework: [ASP.NET] x 


在 Edge 浏览 器 中 ， 按 F12 键 并 选择 Debugger 标签 页 。 

展开 localhost 列表 ， 选 择 pat ate 

在 return 那 一 行 上 打 一 个 断 点 。 

在 输入 框 中 键入 一 些 内 容 ， 确 认 TypeScript 代 码 命 中 断 点 ， 观 察 它 是 否 能 正确 
地 工作 。 


ze coe Du. m 





DOM Explorer Console Debugger io EMETA erformance lem ulation Experimen 






































Find (Ctrl 
Watches 
Type to filter q 1 function sayHello() { t * 
2 const compiler - (document.getElementById("compiler") as HTMLInputElement).value. 
b fj Local Storage 3 const framework = (document.gettlementByld("fremeuork") as HTMLInputElenent).vatue + L9 25] 
p £)sesien Storage ® + return Hello from (compiler) and ${framevork}!” ; pom [object Winden 
b @ Cookies 5 } BO «> @ arguments [object (Arguments)] 
4 i localhost:36285 @ compiler "TypeScriptddddddddd... 
b $$ Content @ framework "ASP.NET" 
b SS Home b [Globals] 
b al Scripts b @ documentgetElem.. [object HTMLInputElem... 
4@ src Add watch 
TSapp.ts 
b $3 localhost:14173 
b $3 Dynamic scripts 
Call stack ^ Breakpoints 
[25] 2 
4 [Main Thread] 
> sayHello app.ts (4, 5) 
onkeyup Index (45, 64) 
v 
< > 











这 就 是 你 需要 知道 的 在 ASPINET 中 使 用 TypeScript 的 基本 知识 了 。 HEF R> 1151 
入 Angular， 写 一 个 简单 的 Angular 程 序 示例 。 


7*1" Angular 2 


使 用 NPM 下 载 依赖 的 包 


添加 Angular 2 和 SystemJS 到 package.json 的 dependencies 里 。 


对 于 VS2015， 新 的 dependencies 列表 如 下 


"dependencies": { 
Yangular2” 259:0-betasd1 
"systemjs": "@.19.24", 
dup OE 
Vdeltb: 42.2.05 

Po 


若 使 用 VS2017， 因 为 NPM3 反 对 同行 的 依赖 (peer dependencies) ， 我 们 需要 把 
Angular 2 同行 的 依赖 也 直接 列 为 依赖 项 : 


"dependencies": { 
Vangular2 w: "2.0, 0-beta. 11", 
"reflect-metadata": "0.1.2", 
Unsa U5.0:0-beta.2". 
ezone se QS ORG 
"systemjs": "0.19.24", 
Supe o.oo 
Moet N2e2 5 

tr 


更 新 tsconfig.json 


现在 安装 好 了 Angular 2 及 其 依赖 项 ， 我 们 需要 启用 TypeScript 中 实验 性 的 装饰 器 支 
持 。 我 们 还 需要 添加 ES2015 的 声明 ， 因 为 Angular 使 用 core-js 来 支持 

像 Promise 的 功能 。 在 未 来 ， 装 饰 器 会 成 为 默认 设置 ， 那 时 也 就 不 再 需要 这 些 设 
置 了 。 


添加 "experimentalDecorators": true, "emitDecoratorMetadata": 

true 到 "compilerOptions" 部 分 。 然后 ， 再 添加 "lib": ["es2015", 
"es5", "dom"] 到 "compilerOptions" ， 以 引入 ES2015 的 声明 。 最 后 ， 我 们 
需要 添加 "./model.ts" 到 "files" 里 ， 我 们 接 下 来 会 创建 它 。 现 

在 tsconfig.json 看 起 来 如 下 : 


"compilerOptions": { 
"nolImplicitAny": true, 
"noEmitOnError": true, 
"sourceMap": true, 
"experimentalDecorators": true, 
"emitDecoratorMetadata": true, 
"Larger "aso 
hb S 

"es2015", "es5", "gom" 
] 

tr 

"piles" 
appr ES i? 

"model rss 
Vestis 6S, 


], 


"compileOnSave": true 


将 Angular 添加 到 gulp 构建 中 


最 后 ， 我 们 需要 确保 Angular 文件 作为 build 的 一 部 分 复制 进来 。 我们 需要 添加 : 


1. 库 文 件 目录 。 
2. 添加 一 个 lib 任务 来 输送 文件 到 wwwroot 。 
3. 在 default 任务 上 添加 lib 任务 依赖 。 


更 新 后 的 gulpfile.js 像 如 下 所 示 : 


/// <binding AfterBuild='default' Clean='clean' /> 
JE 

This file is the main entry point for defining Gulp tasks and us 
ing Gulp plugins. 
Click here to learn more. http://go.microsoft.com/fwlink/?LinkId 
=518007 
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var gulp = require('gulp'); 
var del = require('del'); 


var paths = { 
scrapes: Ik Scripts? /TS m Scripts /StS ""scripts/^ ^7 

*.map'], 
libs: ['node modules/angular2/bundles/angular2.js', 
'node modules/angular2/bundles/angular2-polyfills.js' 


'node modules/systemjs/dist/system.src.js', 
'node modules/rxjs/bundles/Rx.js'] 


c 


gulp.task('lib', function () { 
gulp.src(paths.libs).pipe(gulp.dest('wwwroot/scripts/lib')); 
3); 


gulp.task('clean', function () { 
return del(['wwwroot/scripts/**/*']); 


3); 


gulp.task('default', ['lib'], function () { 
gulp.src(paths.scripts).pipe(gulp.dest('wwwroot/scripts')); 


3); 
此 外 ， 保 存 了 此 gulpfile 后 ， 要 确保 Task Runner Explorer 能 看 到 lib 任务 。 


用 TypeScript 写 一 个 简单 的 Angular 应 用 


首先 ， 将 app.ts Am: 


import {Component} from "angular2/core" 
import {MyModel} from "./model" 


@Component ( { 

selector: my-app ， 

template: ~<div>Hello from ([getCompiler()))«/div»' 
}) 
export class MyApp { 

model = new MyModel(); 

getCompiler() { 

return this.model.compiler; 


接着 在 scripts 中 添加 TypeScript 文 件 model.ts : 
export class MyModel { 
compiler = "TypeScript"; 
再 在 scripts 中 添加 main.ts 
import {bootstrap} from "angular2/platform/browser"; 


import {MyApp} from "./app"; 
bootstrap(MyApp) ; 


后 ， 将 index.html XX: 


xs 


<!DOCTYPE html» 
«html» 
«head» 
«meta charset="utf-8" /> 
<script src="scripts/lib/angular2-polyfills.js"></script> 
<script src="scripts/lib/system.src.js"></script> 
<script src="scripts/lib/rx.js"></script> 
<script src="scripts/lib/angular2.js"></script> 


<script> 
System. config({ 
packages: { 


ESCEADUS sy 
format: 'cjs' 
defaultExtension: 'js' 


3): 


System.import('scripts/main').then(null, console.error.bind( 
console)); 
«/script» 
<title></title> 
</head> 
<body> 
<my -app>Loading. ..</my-app> 
</body> 
</html> 


这 里 加 载 了 此 应 用 。 2447 ASP.NET 应 用 ， 你 应 该 能 看 到 一 个 div 显 示 "Loading..…" 紧 
接着 更 新 成 显示 "Hello from TypeScript" ° 


ASP.NET 4 


注意 : 此 教程 已 从 官方 删除 


安装 TypeScript 


如 果 你 使 用 的 Visual Studio 版 本 还 不 支持 TypeScript ， 你 可 以 安装 Visual Studio 


2015 或 者 Visual Studio 2013。 这 个 快速 上 手指 南 使 用 的 是 Visual Studio 2015 ° 


. 选择 ASPNET Web Application 








New project ? x 
b Recent .NET Framework 4.5.2 ~ Sort by: Default - 3 Search Installed Templates (Ctrl+ E) »- 
4 Installed cs a z 
Kl Blank App (Universal Windows) Visual C# Type: Visual C* 
4 Templates A project template for creating ASP.NET 
cs z 
4 Visual C = BlankcApo (ini I Wind 81 Visual C# applications. You can create ASP.NET Web 
> Wind Ml anc CppiumpecdUningows on) Le Forms, MVC, or Web API applications and 
COM s add many other features in ASP.NET. 
Web | ] Windows Forms Application Visual C# ek z 
b Office/SharePoint @ Application Insights 
Android ET WPF Application Visual C£ [C] Add Application Insights to project 
Apple Watch - Optimize performance and monitor 
Cloud EN Console Application Visual C& Iden your wespplicapon: 


-Pl 
Cross-Platform al nathansa@microsoft.com (Micr.. " 























Extensibility Fy : á : 
SEU m Hub App (Universal Windows 8.1) Visual C# Visual Studio - Data Catalog 
: c Send telemetry to: 
eg Ex] ASP.NET Web Application Visual C Y 
iPhone 
: : ce z : 
lea Shared Project Visual C# Configure settings... 
eporting 
Silverlight n cu : ‘ h à H Help me understand Application Insights 
€ Pr Class Library (Portable for iOS, Android and Windows) Visual C# Privacy statement 
Universal n c , : 
GE Pr Class Library Visual C 
Workflow cs , g 
TNS pii Class Library (Portable) Visual C# = 
P Online Click here to go online and find templates. 
Name: WebApplicationS 
Location: c:\users\nathansa\documents\visual studio 2015\Projects - Browse... 
Solution: Create new solution ~ 
Solution name: WebApplicationS V] Create directory for solution 
Add to TFVC source control 























OK Cancel 








5. 选择 MVC 


ASP.NET 4 


取消 复 选 "Host in the cloud" 本 指南 将 使 用 一 个 本 地 示例 。 





New ASP.NET Project - WebApplication5 


Select a template: 


ASP.NET 4.5.2 Templates 


4 A 
8 e- 
Empty Web Forms 


ni gi 


Azure API App Azure Mobile 


Web API Single Page 
Application 





(Preview) Service 
ASP.NET 5 Templates 
5 
5J 


Get ASP.NET 5 RC 


Add folders and core references for: 


Web Forms Y MVC [_] Web API 




















Add unit tests 





Test project name: — WebApplication5.Tests 








A project template for creating ASP.NET MVC 
applications. ASP.NET MVC allows you to build 
applications using the Model-View-Controller 
architecture. ASP.NET MVC includes many features that 
enable fast, test-driven development for creating 
applications that use the latest standards. 


Learn more 


Change Authentication 


Authentication: Individual User Accounts 


& Microsoft Azure 
(a) C] Host in the cloud 


Web App Y 





运行 此 应 用 以 确保 它 能 正常 工作 。 


洒 加 TypeScript 


下 一 步 我 们 为 TypeScript 添加 一 个 文件 夹 。 
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Application5\Project_Readme.html 


‘ation 


Search Solution Explorer (Ctrl«;) 





网 Solution 'WebApplication5' (1 project) 











DEPLOY GE 
IC Ensure your app is ready for Ge 
[S Area... 
4 各 New Item... Ctrl+Shift+A 
"cp Existing Item... Shift-Alt-A 






New Scaffolded Item... 
*4 New Folder 


Azure API App SDK... 
Azure API App Client... 
s New Azure WebJob Project 
Existing Project as Azure WebJob 
Reference... 
n Service Reference... 
tp Connected Service... 
Analyzer... 
TypeScript File 
TypeScript JSX File 
HTML Page 
JavaScript File 
Style Sheet 
Web Form 


Ms Class... 





Ee 





日 x 


Build 
Rebuild 
Clean 
View 
Analyze 
Convert 
Publish... 


Configure Azure AD Authentication... 
Add Application Insights Telemetry... 


Scope to This 

New Solution Explorer View 
Show on Code Map 
Manage NuGet Packages... 
Set as StartUp Project 
Debug 

Initialize Interactive with Project 
Source Control 

Cut 

Paste 

Remove 

Rename 

Unload Project 

Open Folder in File Explorer 


Properties 





sx Applications 
operties 
eferences 
pp_Data 
pp_Start 
ontent 
ontrollers 

> ints 

odels 

Fripts 

ews 
vicon.ico 
obal.asax 
ackages.config 
roject Readme.html 
artup.cs 

feb.config 


Ctri- X 
Ctrl+V 
Del 


Alt+ Enter 














将 文件 夹 命 名 为 src 


32 


ASP.NET 4 


COom|e-Soap|s-& 
Search Solution Explorer (Ctrl+;) 
网 Solution 'WebApplication5' (1 project) 
4 &] WebApplication5 
b Properties 
-E References 


©) App Data 
©) App_Start 
©) Content 
©) Controllers 
©) fonts 

© Models 
© Scripts 





b © Views 
favicon.ico 
b 4) Global.asax 
42) packages.config 
L3] Project Readme.html 
b C* Startup.cs 
bp «4? Web.config 


添加 TypeScript 代码 


在 src 上 右 击 并 选择 New ltem ° 接着 选择 TypeScript File 并 将 此 文件 命名 为 
app.ts ° 
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Add New Item - WebApplication5 ? x 
4 Installed Sort by: Default - E :三 Search Installed Templates (Ctrl+ 日 P- 
4 Visual CË HTML Page g JSON Schema File Type: Visual C# 
Code 5 : 
Fem JavaScript File LT JSXFile A blank TypeScript source file 
General Style Sheet mi) LESS Style Sheet 
pun Web Form MVC 5 Layout Page (Razor) 
General 
Markup Web Form with Master Page MVC 5 Partial Page (Razor) 
MVC MVC 5 View Page (Razor) JA OWIN Startup class 
Razor 
Scripts MVC 5 View Page with Layout (Razor) A SCSS Style Sheet (SASS) 
SignalR Web API Controller Class (v2.1) & Site Map 
€— SignalR Hub Class (v2 E Typescript File 
Web Forms igna ub Class (v2) ypeScript File 
Windows Forms SignalR Persistent Connection Class... £  TypeScript JSON Configuration File 
WPF ASP.NET Handler Bl TypeScript JSX File 
b Cross-Platform 
Reporting ASP.NET Module & WCF Data Service 5.6.4 
Silverlight Browser File @ WCF Service 
SQL Server 
Workflow CoffeeScript File Gb WCF Service (Ajax-enabled) 
PowerShell Dynamic Data Field y Web Configuration File 
b Online Generic Handler Web Forms Master Page 
JSON File Web Forms Master Page (Nested) 
4 > 
Click here to go online and find templates. 
Name: app.ts 








添加 示例 代码 


将 以 下 代码 写 入 app.ts 文件 。 


function sayHello() { 

const compiler = (document.getElementById("compiler") as HTM 
LInputElement ).value; 

const framework = (document.getElementById("framework") as H 
TMLInputElement).value; 

return "Hello from ${compiler} and $[framework]!'; 


构建 设置 


右 击 项 目 并 选择 New Item 接着 选择 TypeScript Configuration File 保持 文件 
的 默认 名 字 为 tsconfig.json 。 


ASP.NET 4 

















Add New Item - WebApplication3 ? x 
4 Installed Sort by: Default ~ | | = Search Installed Templates (Ctrl+ 日 »- 
4 Visual C$ HTML Page £T JSON Schema File Type: Visual C 
Code JavaScript File ST JsxFile JSON configuration file for the TypeScript 
Data compiler 
General Style Sheet mi) LESS Style Sheet 
“ Ws Web Form MVC 5 Layout Page (Razor) 
General 
Markup Web Form with Master Page [] MVC 5 Partial Page (Razor) 
MVC MVC 5 View Page (Razor) JA OWIN Startup class 
Razor 
Scripts MVC 5 View Page with Layout (Razor) SCSS Style Sheet (SASS) 
SignalR Web API Controller Class (v2.1) i Site Map 
€— SignalR Hub Class (v2) B TypeScript Fil 
Web Forms ignalR Hub Class (v. ypeScript File 
Windows Forms SignalR Persistent Connection Class... PAC ON Configuration File 
WPF ASP.NET Handler Bl TypeScript JSX File 
b Cross-Platform 
Reporting ASP.NET Module & WCF Data Service 5.6.4 
Silverlight Browser File Gb WCF Service 
SQL Server 
Workflow CoffeeScript File Gb WCF Service (Ajax-enabled) 
PowerShell Dynamic Data Field yD Web Configuration File 
> Online Generic Handler Web Forms Master Page 
JSON File Web Forms Master Page (Nested) 
4 > 
Click here to go online and find templates. 
Name: tsconfig.json 








将 默认 的 tsconfig.json 内 容 改 为 如 下 所 示 : 


"compilerOptions": { 
"noImplicitAny": true, 
"noEmitOnError": true, 
"sourceMap": true, 
"target": “ess”, 
-OWED !; "7 SCripts/ App. 

tr 

"Tales. 

V she/dDDete 

], 


"compileOnSave": true 


看 起 来 和 默认 的 设置 差不多 ， 但 注意 以 下 不 同 之 处 : 


1. 设置 "noImplicitAny": true ° 
2. 特别 是 这 里 "outDir": "./Scripts/App" ° 
3. 显 式 列 出 了 "files" 而 不 是 依据 "excludes" 选项 。 
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4. 设置 "compileOnSave": true ° 


当 你 写 新 代码 时 ， 设 置 "noImplicitAny" 选项 是 个 好 主意 一 这 可 以 确保 你 不 会 
错 写 任何 新 的 类 型 。 设置 "compileonsave" 选项 可 以 确保 你 在 运行 web 程序 前 
自动 编译 保存 变更 后 的 代码 。 更 多 信息 请 参见 the tsconfig.json documentation » 


在 视图 中 调用 脚本 


1. 在 Solution Explorer 中 , 打开 Views | Home| Index.cshtml 。 


Solution Explorer 


$|o-Sos5m^- 


Search Solution Explorer (Ctrl+;) 


fg] Solution 'WebApplication5' (1 project) 
4 8] WebApplication5 
b £ Properties 
> ml References 
©) App Data 
©) App. Start 
©) Content 
©) Controllers 
© fonts 
©) Models 
大 Scripts 
fal src 
TS app.ts 
Sl Views 
b ©) Account 
4 — Home 
[&] About.cshtml 
[&] Contact.cshtml 
(5) Index.cshtm! 
b ©) Manage 
b ©) Shared 
[@] _ViewStart.cshtml 
H Web.config 
favicon.ico 
b 43) Global.asax 
4.) packages.config 
L3 Project Readme.html 
b C* Startup.cs 
b 4? Web.config 





2. 修改 代码 如 下 : 
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Qt 

ViewBag.Title - "Home Page"; 
} 
<script src="~/Scripts/App/app.js"></script> 
<div id="message"></div> 
<div> 

Compiler: <input id="compiler" value="TypeScript" onkeyup 
="document.getElementById('message').innerText = sayHello()" 
/><br /> 

Framework: <input id="framework" value="ASP.NET" onkeyup= 
"document .getElementById('message').innerText = sayHello()" 
es 
</div> 


Ei — o Se 


测 试 


1. 运行 项 目 。 
2. 在 输入 框 中 键入 时 ， 您 应 该 看 到 一 个 消息 : 





© Home Page - My ASP.NI X 十 


pes 5 È | localhost 





Hello from TypeScript and ASP.NET! 
Compiler: |TypeScript 


Framework: |ASP.NET| x 


在 Edge 浏览 器 中 , 4x F12 键 并 选择 Debugger 标签 页 。 

展开 localhost 列表 , 选择 — 

在 return 那 一 行 上 打 一 个 断 点 

在 输入 框 中 键入 一 些 内 容 ， 确 认 TypeScript 代 码 命 中 断 点 ， 观 察 它 是 
地 工作 。 


pe B I op 


m! 
zu 
GG 
m 
B 


DOM Explorer Console Debugger io EEY Performance 
> b. & P. UW OO- 








Type to filter n 











b fil Local Storage 
b £ Session Storage 
b & Cookies 
4 i localhost:36285 
b Si Content 
b SS Home 
b lll Scripts 
4 V src 
TSapp.ts 
b $$ localhost:14173 
> lll Dynamic scripts 





fal 





1 function sayHello() ( 
2 
3 
4 
5 


t 


< 


Memory 


Emulation 





Experiments 


EC] 


const compiler - (document.getElementById("compiler") as HTMLInputElement).value; i 
4 [Locals] 
const framework = (document.getElementById("framework") as HTMLInputElement) .value ] 


> 











BY Watches 





^ 


b @ this 
i. be arguments 
@ compiler 
@ framework 
[Global 
b @ document.getElem... 
Add watch 


Call stack ^ Breakpoints 


4 [Main Thread] 
中 sayHello 
onkeyup 


[object Window] 

[object (Arguments)] 
"TypeScriptddddddddd... 
"ASP.NET" 


[object HTMLInputElem... 


res 


app.ts (4, 5) 
Index (45, 64) 





这 就 是 你 需要 知道 的 在 ASPNET 中 使 用 TypeScript 的 基本 知识 了 。 接 下 来 ， 我 们 引 
入 Angular， 写 一 个 简单 的 Angular 程 序 示例 。 


Aa Angular 2 


使 用 NPM 下 载 所 需 的 包 


1. 安装 Packagelnstaller ° 


2. 用 Packagelnstaller 来 安装 Angular 2 > systemjs 和 Typings ° 


在 project 上 右 击 , 选择 Quick Install Package ° 








*t& Quick Install Package » d 


Dl npm ~ angular2 bi Latest version ~ 


npm install angular2 --save-dev 


Tip: Type 'j:' to select JSPM from dropdown 








“Wi Quick Install Package x 


ni npm  "* systemjs M Latest version 


npm install systemjs --save-dev 


Tip: Type 'b:' to select Bower from dropdown Install 


并 Quick Install Package x 








n npm ~ typingd Y Latest version M 


npm install typings --save-dev 


Tip: Type 'j:' to select JSPM from dropdown Install Cancel 


3. 用 Packagelnstaller 安装 es6-shim 的 类 型 文件 。 











Angular 2 包含 es6-shim 以 提供 Promise 支持 , 但 TypRSCHpESE 需要 它 的 类 型 
文件 。 在 Packagelnstaller 中 , 选择 Typing 替换 nom 选项 。 接 着 键入 "es6- 









es6-shim| M Latest version y 


dhim --ambient --save 


Tip: Type 'ty:' to select Typings from dropdown Install Cancel 








更 新 tsconfig.json 


现在 安装 好 了 Angular 2 及 其 依赖 项 ， 我 们 还 需要 局 用 中 实验 性 的 装饰 
器 支持 并 且 引 入 es6-shim 的 类 型 文件 。 将 来 的 版 本 中 ， 装 饰 器 和 ESO 选项 将 成 为 
默认 选项 ， 我 们 就 可 以 不 做 此 设置 了 。 添加 "experimentalDecorators": true, 
"emitDecoratorMetadata": true 选项 到 "compilerOptions" ， 再 添 


Ja "./typings/index.d.ts" 到 "files" 。 最 后 ， 我 们 要 新 
4 "./src/model.ts" 文件 ， 并 且 得 把 它 加 到 "files" 里 。 现 


mi 


在 tsconfig.json 应 该 是 这 样 : 


"compilerOptions": { 
"noImplicitAny": false, 
"noEmitOnError": true, 
"sourceMap": true, 

"Larger": “ess”, 
"experimentalDecorators": true, 
"emitDecoratorMetadata": true, 
Voutbur' : " /ScriptsZADp" 

ty 

"iles": 

“af Spp/Zappbs- 
"./src/model.ts", 

i Shey Mall.cs A 
"./typings/index.d.ts" 


添加 CopyFiles 到 build 中 


最 后 ， 我 们 需要 确保 Angular 文件 作为 build 的 一 部 分 复制 进来 。 这 样 操 作 ， 右 击 
项 目 选择 'Unload' ， 再 次 右 击 项 目 选择 'Edit csproj » 在 TypeScript 配置 项 
PropertyGroup 之 后 ， 添 加 一 个 temGroup 和 Target 配置 项 来 复制 Angular X 
件 。 


<ItemGroup> 

<NodeLib Include="$(MSBuildProjectDirectory ) \node_modules\angu 
lar2\bundles\angular2.js"/> 

<NodeLib Include="$(MSBuildProjectDirectory )\node_modules\angu 
lar2\bundles\angular2-polyfills.js"/> 

<NodeLib Include="$(MSBuildProjectDirectory )\node_modules\syst 
emjsNdistNsystem.src.js"/» 

<NodeLib Include="$(MSBuildProjectDirectory )\node_modules\rxjs 
\bundles\Rx.js"/> 
</ItemGroup> 
<Target Name="CopyFiles" BeforeTargets="Build"> 

<Copy SourceFiles="@(NodeLib)" DestinationFolder="$(MSBuildPro 
jectDirectory)\Scripts"/> 
</Target> 


现在 ， 在 工程 上 右 击 选择 重新 加 载 项 目 。 此 时 应 当 能 在 解决 方案 资源 管理 器 
(Solution Explorer) 中 看 到 node_modules 。 


用 TypeScript 写 一 个 简单 的 Angular 应 用 
首先 ， 将 app.ts AA : 


import {Component} from "angular2/core" 
import {MyModel} from "./model" 


@Component ( { 

selector: my-app , 

template: ~<div>Hello from {{getCompiler()}}</div>- 
3) 
class MyApp ( 

model = new MyModel(); 

getCompiler() { 

return this.model.compiler; 


接着 在 src 中 添加 TypeScript X fF model.ts : 


export class MyModel { 
compiler = "TypeScript"; 


再 在 src 中 添加 main.ts 


import {bootstrap} from "angular2/platform/browser"; 
import {MyApp} from "./app"; 
bootstrap(MyApp); 


最 后 ， 将 Views/Home/Index.cshtml AA. : 


Qt 
ViewBag.Title - "Home Page"; 
} 
<script src="~/Scripts/angular2-polyfills.js"></script> 
<script src="~/Scripts/system.src.js"></script> 
<script src="~/Scripts/rx.js"></script> 
<script src="~/Scripts/angular2.js"></script> 
<script> 
System. config({ 
packages: { 
Scripts /Appi i 
format: 'cjs', 
defaultExtension: 'js' 


}); 

System.import('/Scripts/App/main').then(null, console.error. 
bind(console)); 
</SCript= 
<my -app>Loading. ..</my-app> 


这 里 加 载 了 此 应 用 。 运行 ASP.NET 应 用 ， 你 应 该 能 看 到 一 个 div 显示 "Loading..." 
紧 接 着 更 新 成 显示 "Hello from TypeScript" 。 
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这 篇 快速 上 手指 南 将 教 你 如 何 使 用 Gulp 构 建 TypeScript， 和 如 何在 Gulp 管 道里 添 
加 Browserify，uglify 或 Watchify。 它 还 包涵 了 Babel 的 功能 ， 通 过 使 用 Babelify。 


这 里 假设 你 已 经 在 使 用 Node.js 和 npm 了 。 


创建 简单 工程 
我 们 首先 创建 一 个 新 目录 。 命名 为 proj ， 也 可 以 使 用 任何 你 喜欢 的 名 字 。 


mkdir proj 
cd proj 


我 们 将 以 下 面 的 结构 开始 我 们 的 工程 : 
proj/ 


| src/ 
L- dist/ 


TypeScript 文 件 放 在 src 文件 夹 下 ， 经 过 TypeScript 编 译 器 编译 生成 的 目标 文件 放 
在 dist 目录 下 。 


下 面 让 我 们 来 创建 这 些 文件 夹 : 


mkdir src 
mkdir dist 


初始 化 工程 
现在 让 我 们 把 这 个 文件 夹 转换 成 npm 包 : 
npm init 
你 将 看 到 有 一 些 提示 操作 。 除了 入 口 文件 外 ， 其 余 的 都 可 以 使 用 默认 项 。 入口 文 


件 使 用 ./dist/main.js ° 你 可 以 随时 在 package.json 文件 里 更 改 生成 的 配 
go 


安装 依赖 项 


现在 我 们 可 以 使 用 npm install 命令 来 安装 包 。 首先 全 局 安装 gulp-cli (+ 
果 你 使 用 Unix 系 统 ， 你 可 能 需要 在 npm install 命令 上 使 用 sudo ) ° 


npm install -g gulp-cli 


然后 安装 typescript ， gulp 和 gulp-typescript 到 开发 依赖 项 。 Gulp- 
typescript 是 TypeScript 的 一 个 Gulp 插 件 。 


npm install --save-dev typescript gulp gulp-typescript 


写 一 个 简单 的 例子 
让 我 们 写 一 个 Hello World 程序。 在 src 目录 下 创建 main.ts 文件 : 


function hello(compiler: string) { 
console.log( Hello from $(compiler]'); 


j 
hello("TypeScript"); 


在 工程 的 根 目 录 proj 下 新 建 一 个 tsconfig.json 文件 : 


{ 

"files": [ 
'sre/main. tS" 

], 

"compilerOptions": { 
"noImplicitAny": true, 
"target: = “ess” 

} 

} 


新 建 gulpfile.js 文件 


在 工程 根 目 录 下 ， 新 建 一 个 gulpfile.js 文件 : 


var gulp = require("gulp"); 

var ts = require("gulp-typescript"); 

var tsProject = ts.createProject("tsconfig.json"); 

gulp.task("default", function () { 

return tsProject.src() 

.pipe(tsProject()) 
.Js.pipe(gulp.dest("dist")); 

3); 


测试 这 个 应 用 


gulp 
node dist/main.js 


程序 应 该 能 够 打印 出 "Hello from TypeScript!” ° 


向 代码 里 添加 模块 


在 使 用 Browserify 前 ， 让 我 们 先 构建 一 下 代码 然后 再 添加 一 些 混入 的 模块 。 
构 将 是 你 在 申 实 应 用 程序 中 会 用 到 的 。 


新 建 一 个 src/greet.ts 文件 : 
export function sayHello(name: string) { 
return "Hello from $[name) ; 
更 改 src/main.ts 代码 ， 从 greet.ts 导入 sayHello 


import { sayHello } from "./greet"; 


console.log(sayHello("TypeScript")); 


这 个 结 


最 后 ， 将 src/greet.ts 添加 到 tsconfig.json 


‘Piles: [p 
"src/main.ts", 
"src/greet.ts" 


], 

"compilerOptions": { 
"noImplicitAny": true, 
"target": "esb5" 


确保 执行 gulp 后 模块 是 能 工作 的 ， 在 Node.js 下 进行 测试 : 


gulp 
node dist/main.js 


注意 ， 即 使 我 们 使 用 了 ES2015 的 模块 语法 ，TypeScript 还 是 会 生成 Node.js 使 用 的 
oL sao 我 们 在 这 个 教程 里 会 一 直 使 用 CommonJS 模 块 ， 但 是 你 可 以 通 
过 修改 module 选项 来 改变 这 个 行为 。 


Browserify 


现在 ， 让 我 们 把 这 个 工程 由 Node. PARRA 浏览 器 环境 里 。 因此 ， 我 们 将 把 所 有 
模块 捆绑 成 一 个 JavaScript 文 件 。 所幸， 这 正 是 Browserify 要 做 的 事情 。 更 方便 的 
是 ， 它 支持 Node.js 的 CommonJS 模 块 ， 这 也 正 是 TypeScript 默 认 生 成 的 类 型 。 也 
就 是 说 TypeScript 和 Node.js 的 设置 不 需要 改变 就 可 以 移植 到 浏览 器 里 。 


首先 ， 安 装 Browserify，tsify 和 vinyl-source-stream 。 tsify 是 Browserify 的 一 个 插 
件 ， 就 像 gulp-typescript 一 样 ， 它 能 够 访问 TypeScript 编 译 器 。 vinyl-source-stream 
会 将 Browserify 的 输出 文件 适 配 成 gulp 能 够 解析 的 格式 ， 它 叫做 vinyl 。 


npm install --Save-dev browserify tsify vinyl-source-stream 


新 建 一 个 页 面 
在 src 目录 下 新 建 一 个 index.html 文件 : 


<!DOCTYPE html> 


«html» 
«head» 
«meta charset="UTF-8" /> 
<title>Hello World!</title> 
</head> 
<body> 
<p id="greeting">Loading ...</p> 
<script src="bundle.js"></script> 
</body> 
</html> 


修改 main.ts 文件 来 更 新 这 个 页 面 : 
import { sayHello } from "./greet"; 


function showHello(divName: string, name: string) ( 
const elt = document.getElementById(divName); 
elt.innerText = sayHello(name); 


showHello("greeting", "TypeScript"); 


showHello 调用 sayHello 函数 更 改 页 面 上 段落 的 文字 。 现在 修改 gulpfile 文 件 
如 下 : 


var gulp = require("gulp"); 
var browserify = require("browserify"); 
var source - require('vinyl-source-stream'); 
var tsify = require("tsify"); 
var paths - ( 
pages: ['src/*.html'] 
3 


gulp.task("copy-html", function () { 
return gulp.src(paths.pages) 
.pipe(gulp.dest("dist")); 
3); 


gulp.task("default", ["copy-html"], function () { 
return browserify({ 
basedir: '.', 
debug: true, 
entries: ['src/main.ts'], 
cache: {}, 
packageCache: {} 


3) 

.plugin(tsify) 

.bundle() 

.pipe(source( 'bundle.js')) 

-pipe(gulp.dest("dist")); 
3); 


这 里 增加 了 copy-html 任务 并 且 把 它 加 作 default 的 依赖 项 。 这 样 ， 

当 default 执行 时 ， copy-html 会 被 首先 执行 。 我们 还 修改 了 default 任 
务 ， 让 它 使 用 tsify 插件 调用 Browserify， 而 不 是 gulp-typescript ° 方便 的 
是 ， 两 者 传递 相同 的 参数 对 象 到 TypeScript 编 译 器 。 


调用 bundle 后 ， 我 们 使 用 source (vinyl-source-stream 的 别名 ) 把 输出 文件 命 
名 为 bundle.js ° 


测试 此 页 面 ， 运行 gulp ， 然 后 在 浏览 器 里 打开 dist/index.html 。 你 应 该 能 
在 页 面 上 看 到 “Hello from TypeScript” ° 


注意 ， 我 们 为 Broswerify 指 定 了 debug: true 。 这 会 让 tsify 在 输出 文件 里 生 
成 source maps ° source maps 允许 我 们 在 浏览 器 中 直接 调试 TypeScript 源 
码 ， 而 不 是 在 合并 后 的 JavaScript 文 件 上 调试 。 你 要 打开 调试 器 并 在 main.ts € 
打 一 个 断 点 ， 看 看 source maps 是 否 能 工作 。 当 你 刷新 页 面 时 ， 代 码 会 停 在 断 点 
处 ， 从 而 你 就 能 够 调试 greet.ts 。 


Watchify > Babel 和 Uglify 


现在 代码 已 经 用 Browserify 和 tsify 捆 绑 在 一 起 了 ， 我 们 可 以 使 用 Browserify 插 件 为 构 
建 添加 一 些 特 性 。 


。Watchify 启 动 Gulp 并 保持 运行 状态 ， 当 你 保存 文件 时 自动 编译 。 帮 你 进入 到 编 
辑 -保存 -刷新 浏览 器 的 循环 中 。 


e Babel 是 个 十 分 灵活 的 编译 器 ， 将 ES2015 及 以 上 版 本 的 代码 转换 成 ES5 和 
ES3。 你 可 以 添加 大 量 自 定义 的 TypeScript 目 前 不 支持 的 转换 器 。 


e. Uglify 帮 你 压缩 代码 ， 将 花费 更 少 的 时 间 去 下 载 它们 。 
Watchify 
我 们 启动 Watchify， 让 它 在 后 台 帮 我 们 编译 : 


npm install --save-dev watchify gulp-util 


修改 gulpfile 文 件 如 下 : 


var gulp = require("gulp"); 
var browserify = require("browserify"); 
var source = require('vinyl-source-stream' ); 
var watchify = require("watchify"); 
var tsify = require("tsify"); 
var gutil = require("gulp-util"); 
var paths = { 
pages: ['src/*.html'] 
H 


var watchedBrowserify = watchify(browserify({ 
basedir: '.', 
debug: true, 
entries: ['src/main.ts'], 
cache: {}, 
packageCache: {} 
3)-plugin(tsify)); 


gulp.task("copy-html", function () { 
return gulp.src(paths.pages) 
.pipe(gulp.dest("dist")); 
3); 


function bundle() { 
return watchedBrowserify 
.bundle() 
.pipe(source('bundle.js')) 
.pipe(gulp.dest("dist")); 


gulp.task("default", ["copy-html"], bundle); 
watchedBrowserify.on("update", bundle); 
watchedBrowserify.on("log", gutil.log); 


共有 三 处 改变 ， 但 是 需要 你 略微 重 构 一 下 代码 。 


1. 将 browserify ZA ERE watchify 的 调用 里 ， 控 制 生成 的 结果 。 
2. 调用 watchedBrowserify.on("update", bundle); ， 每 次 TypeScript 文 件 
改变 时 Browserify 会 执行 bundle 函数 。 


3. 调用 watchedBrowserify.on("log", gutil.log); 将 日 志 打 印 到 控制 台 。 


(1) 和 (2) 在 一 起 意味 着 我 们 要 将 browserify 调用 移出 default 任务 。 RE Ah 
数 起 个 名 字 ， 因 为 Watchify 和 Gulp 都 要 调用 它 。(3) 是 可 选 的 ， 但 是 对 于 调试 来 讲 
很 有 用 。 


现在 当 你 执行 gulp ， 它 会 启动 并 保持 运行 状态 。 试 着 改变 main.ts 文件 
里 showHello 的 代码 并 保存 。 你 会 看 到 这 样 的 输出 : 


proj$ gulp 

[10:34:20] Using gulpfile ~/src/proj/gulpfile.js 
[10:34:20] Starting 'copy-html'... 

[10:34:20] Finished 'copy-html' after 26 ms 
[10:34:20] Starting 'default'... 

[10:34:21] 2824 bytes written (0.13 seconds) 
[10:34:21] Finished 'default' after 1.36 s 
[10:35:22] 2261 bytes written (0.02 seconds) 
[10:35:24] 2808 bytes written (0.05 seconds) 


Uglify 


首先 安装 Uglify。 因为 Uglify 是 用 于 混淆 你 的 代码 ， 所 以 我 们 还 要 安装 vinyl-buffer 和 
gulp-sourcemaps 来 支持 sourcemaps。 


npm install --save-dev gulp-uglify vinyl-buffer gulp-sourcemaps 


修改 gulpfile 文 件 如 下 : 


var gulp = require("gulp"); 
var browserify = require("browserify"); 
var source = require('vinyl-source-stream' ); 
var tsify = require("tsify"); 
var uglify = require('gulp-uglify'); 
var sourcemaps = require('gulp-sourcemaps'); 
var buffer = require('vinyl-buffer'); 
var paths = { 
pages: ['src/*.html' ] 
3 


gulp.task("copy-html", function () { 
return gulp.src(paths.pages) 
.pipe(gulp.dest("dist")); 
3); 


gulp.task("default", ["copy-html"], function () { 
return browserify({ 
basedir: '.', 
debug: true, 
entries: ['src/main.ts'], 
cache: {}, 
packageCache: {} 
3) 
.plugin(tsify) 
.bundle() 
.pipe(source('bundle.js')) 
.pipe(buffer()) 
.pipe(sourcemaps.init(([loadMaps: true})) 
.pipe(uglify()) 
.pipe(sourcemaps.write('./')) 
.pipe(gulp.dest("dist")); 
3); 


注意 uglify 只 是 调用 了 自己 一 buffer 和 sourcemaps 的 调用 是 用 于 确保 
sourcemaps 可 以 工作 。 这 些 调用 让 我 们 可 以 使 用 单独 的 sourcemap 文 件 ， 而 不 是 
Z aya) Ak 49sourcemaps » 你 现在 可 以 执行 gulp 来 检查 bundle.js 是 否 被 压 
^d: 


gulp 
cat dist/bundle.js 


Babel 

首先 安装 Babelify 和 ES2015 的 Babel 预 置 程序 。 和 Uglify 一 样 ，Babelify 也 会 混淆 代 
码 ， 因 此 我 们 也 需要 vinyl-buffer 和 gulp-sourcemaps。 默认 情况 下 Babelify 只 会 处 理 
扩展 名 为 .js ， .es ， .es6 和 ,jsx 的 文件 ， 因 此 我 们 需要 添加 .ts 扩展 名 


到 Babelify 选 项 。 


npm install --save-dev babelify babel-core babel-preset-es2015 V 
inyl-buffer gulp-sourcemaps 


修改 gulpfile 文 件 如 下 : 


var gulp = require('gulp'); 
var browserify = require('browserify' ); 
var source = require('vinyl-source-stream' ); 
var tsify = require('tsify'); 
var sourcemaps = require('gulp-sourcemaps'); 
var buffer = require('vinyl-buffer'); 
var paths = { 
pages: ['src/*.html'] 
3 


gulp.task('copyHtml', function () { 
return gulp.src(paths.pages) 
.pipe(gulp.dest('dist')); 
3); 


gulp.task('default', ['copyHtml'], function () { 
return browserify({ 
basedir: '.', 
debug: true, 
entries: ['src/main.ts'], 
cache: {}, 
packageCache: {} 
3) 
.plugin(tsify) 
.transform('babelify', ( 
presets: ['es2015'], 
extensions: ['.ts'] 
3) 
. bundle() 
.pipe(source('bundle.js')) 
.pipe(buffer()) 
.pipe(sourcemaps.init(([loadMaps: true})) 
.pipe(sourcemaps.write('./')) 
.pipe(gulp.dest('dist')); 
3); 


我 们 需要 设置 TypeScript 目 标 为 ES2015。 Babel 稍 后 会 从 TypeScript 生 成 的 ES2015 
代码 中 生成 ES5。 修改 tsconfig.json : 


"piles 
"src/main.ts" 

]; 

"compilerOptions": { 
"noImplicitAny": true, 
"target": "es2015" 


对 于 这 样 一 段 简单 的 代码 来 说 ，Babel 的 ES5 输 出 应 该 和 TypeScript 的 输出 相似 。 


注意 : 此 教程 已 从 官方 删除 
这 个 快速 上 手指 南 会 告诉 你 如 何 结 合 使 用 TypeScript 和 Knockout.js。 


这 里 我 们 假设 你 已 经 会 使 用 Node.js 和 npm 


新 建 工 程 


首先 ， 我 们 新 建 一 个 目录 。 暂时 命名 为 proj ， 当 然 了 你 可 以 使 用 任何 喜欢 的 名 
字 o 


mkdir proj 
cd proj 


接 下 来 ， 我 们 按 如 下 方式 来 组 织 这 个 工程 : 
proj/ 


| src/ 


L- built/ 


TypeScript 源 码 放 在 src 目录 下 ， 结 过 TypeScript 编 译 器 编译 后 ， 生 成 的 文件 放 
在 built 目录 里 。 


下 面 创 建 目 录 : 


mkdir src 
mkdir built 


初始 化 工程 
现在 将 这 个 文件 夹 转换 为 Npm 包 。 


npm init 


你 会 看 到 一 系列 提示 。 除了 入 口 点 外 其 它 设置 都 可 以 使 用 默认 值 。 你 可 以 随时 到 
生成 的 package.json 文件 里 修改 这 些 设置 。 


安装 构建 依赖 
首先 确保 TypeScript 已 经 全 局 安装 。 


npm install -g typescript 


我 们 还 要 获取 Knockout 的 声明 文件 ， 它 描述 了 这 个 库 的 结构 供 TypeScript 使 用 。 


npm install --save @types/knockout 


获取 运行 时 依赖 

我 们 需要 Knockout 和 RequireJS。 RequireJS 是 一 个 库 ， 它 可 以 让 我 们 在 运行 时 弄 
步 地 加 载 模 块 。 

有 以 下 几 种 获取 方式 : 


1. 手动 下 载 文件 并 维护 它们 。 
2. 通过 像 Bower 这 样 的 包 管 理 下 载 并 维护 它们 。 
3. 使 用 内 容 分 发 网 络 (CDN) 来 维护 这 两 个 文件 。 


我 们 使 用 第 一 种 方法 ， 它 会 简单 一 些 ， 但 是 Knockout 的 官方 文档 上 有 讲解 如 何 使 用 
CDN ， 更 多 像 RequireJS 一 样 的 代码 库 可 以 在 cdnjs 上 查找 。 


下 面 让 我 们 在 工程 根 目 录 下 创建 externals 目录 。 


mkdir externals 


然后 下 载 Knockout 和 下 载 RequireJS 到 这 个 目录 里 。 最 新 的 压缩 后 版 本 就 可 以 。 


添加 TypeScript 配 置 文件 


下 面 我们 想 把 所 有 的 TypeScript 文 件 整合 到 一 起 - 包括 自己 写 的 和 必须 的 声明 文 
件 。 


我 们 需要 创建 一 个 tsconfig.json 文件 ， 包 含 了 输入 文件 列表 和 编译 选项 。 EL 
程 根 目录 下 创建 一 个 新 文件 tsconfig.json ， 内 容 如 下 : 


"compilerOptions": { 
outputs 
"sourceMap": true, 
"noImplicitAny": true, 
"module": "amd", 
"target": “ess” 
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“让 二 eS 
"./src/require-config.ts", 
(ae SEC; MELLO. ES” 


这 里 引用 了 typings/index.d.ts ， 它 是 Typings 帮 我 们 创建 的 。 这 个 文件 会 自动 
地 包含 所 有 安装 的 依赖 。 


你 可 能 会 对 typings 目录 下 的 browser.d.ts 文件 感到 好 奇 ， 尤 其 因为 我 们 将 在 
浏览 器 里 运行 代码 。 als 因 是 这 样 的 ， 当 目标 为 浏览 器 的 时 候 ， 一 些 包 会 生成 不 
同 的 版 本 。 通常 来 讲 ， 这 些 情况 很 少 发 生 并 且 在 这 里 我 们 不 会 遇 到 这 种 情况 ， 所 以 
我 们 可 以 忽略 browser.d.ts 。 


你 可 以 在 这 里 查看 更 多 关于 tsconfig.json 文件 的 信息 


写 些 代码 


下 面 我 们 使 用 Knockout 写 一 段 TypeScript 代 码 。 首先， 在 src 目录 里 新 建 一 
个 hello.ts 文件 。 


import * as ko from "knockout"; 


class HelloViewModel { 
language: KnockoutObservable<string> 
framework: KnockoutObservable<string> 


constructor(language: string, framework: string) { 
this.language = ko.observable(language) ; 
this.framework = ko.observable( framework) ; 


ko.applyBindings(new HelloViewModel("TypeScript", "Knockout")); 


接 下 来 ， 在 src 目录 下 再 新 建 一 个 require-config.ts 文件 。 


declare var require: any; 
require.config(( 
paths: { 
"knockout": "externals/knockout-3.4.0", 


3): 


这 个 文件 会 告诉 RequireJS 从 哪里 导入 Knockout， 好 比 我 们 在 hello.ts 里 做 的 一 
样 。 你 创建 的 所 有 页 面 都 应 该 在 RequireJS 之 后 和 导入 任何 东西 之 前 引入 它 。 为 了 
更 好 地 理解 这 个 文件 和 如 何 配 置 RequireJS， 可 以 查看 文档 。 


我 们 还 需要 一 个 视图 来 显示 HelloViewModel ° # proj 目录 的 根 上 创建 一 个 文 
fF index.html ， 内 容 如 下 : 


<!DOCTYPE html> 


«html» 
«head» 
«meta charset="UTF-8" /> 
<title>Hello Knockout!</title> 
</head> 
<body> 
<p> 
Hello from 
<strong data-bind="text: language">todo</strong> 
and 
«strong data-bind="text: framework">todo</strong>! 
</p> 
<p>Language: <input data-bind="value: language" /></p> 
<p>Framework: «input data-bind="value: framework" /></p> 
«script src="./externals/require. js"></script> 
<script src="./built/require-config.js"></script> 
<script> 
require(["built/hello"]); 
=/SCh pt 
</body> 
</html> 


注意 ， 有 两 个 Script 标签 。 首先 ， 我 们 引入 RequireJS。 然后 我 们 再 在 require- 
config.js 里 映射 外 部 依赖 ， 这样 RequireJS 就 能 知道 到 哪里 去 查找 它们 。 最 后 ， 
使 用 我 们 要 去 加 载 的 模块 去 调用 require ° 


现在 ， 在 你 喜欢 的 浏览 器 打开 index.html ， 所 有 都 应 该 好 用 了 。 你 应 该 可 以 看 
到 页 面 上 显示 “Hello from TypeScript and Knockout!”° 在 它 下 面 ， 你 还 会 看 到 两 个 
输入 框 。 当 你 改变 输入 和 切换 焦点 时 ， 就 会 看 到 原先 显示 的 信息 改变 了 。 


这 篇 指南 将 会 教 你 如 何 将 TypeScript 和 React 还 有 webpack 结 合 在 一 起 使 用 。 
如 果 你 正在 做 一 个 全 新 的 工程 ， 可 以 先 阅读 这 篇 React 快 速 上 手指 南 。 


否则 ， 我 们 假设 已 经 在 使 用 Node.js 和 npm » 


初始 化 项 目 结构 
让 我 们 新 建 一 个 目录 。 将 会 命名 为 proj ， 但 是 你 可 以 改 成 任何 你 喜欢 的 名 字 。 


mkdir proj 
cd proj 


RAT AAR da 09 25 39 ARRIERE : 


proj/ 
|- dist/ 
L- src/ 
L- components/ 


TypeScript 文 件 会 放 在 src 文件 夹 里 ， 通 过 TypeScript 编 译 器 编译 ， 然 后 经 
Webpack 处 理 ， 最 后 生成 一 个 bundle.js 文件 放 在 dist 目录 下 。 我 们 自 定义 的 
组 件 将 会 放 在 src/components 文件 夹 下 。 


下 面 来 创建 基本 结构 : 


mkdir src 

cd src 

mkdir components 
cd: 


Webpack 会 帮助 我 们 生成 dist 目录 。 


初始 化 工程 


现在 把 这 个 目录 变 成 npm 包 。 


npm init 


你 会 看 到 一 些 提示 ， 放 心地 使 用 默认 值 就 可 以 了 。 当然 ， 你 也 可 以 随时 到 生成 
的 package.json 文件 里 修改 。 


3s odds 
安装 依赖 
首先 确保 已 经 全 局 安装 了 Webpack。 


npm install -g webpack 


Webpack 这 个 工具 可 以 将 你 的 所 有 代码 和 可 选择 地 将 依赖 捆绑 成 一 个 单独 
的 .js 文件 。 


现在 我 们 添加 React 和 React-DOM 以 及 它们 的 声明 文件 到 package.json 文件 里 做 
为 依赖 : 


npm install --save react react-dom Qtypes/react @types/react -dom 


使 用 @types/ 前 组 表示 我 们 额外 要 获取 React 和 React-DOM 的 声明 文件 。 通常 当 
你 导入 像 "react" 这 样 的 路 径 ， 它 会 查看 react 6; 然而 ， 并 不 是 所 有 的 包 都 
包含 了 声明 文件 ， 所 以 TypeScript 还 会 查看 @types/react Be 你 会 发 现 我 们 以 
后 将 不 必 在 意 这些 。 


接 下 来 ， 我 们 要 添加 开发 时 依赖 awesome-typescript-loader 和 source-map-loader ° 


npm install --save-dev typescript awesome-typescript-loader sour 
ce-map-loader 


这 些 依 赖 会 让 TypeScript 和 webpack 在 一 起 良好 地 工作 。 awesome-typescript- 
loader 可 以 让 Webpack 使 用 TypeScript 的 标准 配置 文件 tsconfig.json 编译 
TypeScript 代 码 。 source-map-loader 使 用 TypeScript 输 出 的 sourcemap 文 件 来 告诉 
Webpack 何 时 生成 自己 的 Sourcemaps。 这 就 允许 你 在 调试 最 终生 成 的 文件 时 就 好 
像 在 调试 TypeScript 源 码 一 样 。 


注意 我 们 安装 TypeScript 为 一 个 开发 依赖 。 我 们 还 可 以 使 用 npm link 
typescript 来 链接 TypeScript 到 一 个 全 局 拷贝 ， 但 这 不 是 常见 用 法 。 


添加 TypeScript 配 置 文件 


我 们 想 将 TypeScript 文 件 整 合 到 一 起 - 这 包括 我 们 写 的 源码 和 必要 的 声明 文件 。 


我 们 需要 创建 一 个 tsconfig.json 文件 ， 它 包含 了 输入 文件 列表 以 及 编译 选项 。 
在 工程 根 目 录 下 新 建文 件 tsconfig.json 文件 ， 添 加 以 下 内 容 : 


"compilerOptions": { 
HOUWEDI dst 
"sourceMap": true, 
"noImplicitAny": true, 
"module": "commonjs", 
“Larger < Meso, 
DISKE “react 

tr 

"include": [ 

SME E we 


你 可 以 在 这 里 了 解 更 多 关于 tsconfig.json 文件 的 说 明 。 


些 代 码 


下 面 使 用 React 写 一 段 TypeScript 代 码 。 首先 ， 在 src/components 目录 下 创建 一 
个 名 为 Hello.tsx 的 文件 ， 代 码 如 下 


import * as React from "react"; 


export interface HelloProps { compiler: string; framework: strin 
9g; j 


export const Hello = (props: HelloProps) => <hi>Hello from {prop 
s.compiler) and {props.framework}!</h1>; 


注意 这 个 例子 使 用 了 无 状态 的 功能 组 件 ， 我 们 可 以 让 它 更 像 一 点 类 。 


import * as React from "react"; 


export interface HelloProps { compiler: string; framework: strin 
9g; j 


// 'HelloProps' describes the shape of props. 
// State is never set so we use the '{}' type. 
export class Hello extends React.Component«HelloProps, {}> { 
render() ( 
return <hi>Hello from {this.props.compiler} and {this.pr 
ops. framework}!</h1>; 


} 


接 下 来 ， 在 src 下 创建 index.tsx 文件 ， 源 码 如 下 : 


import * as React from "react"; 
import * as ReactDOM from "react-dom"; 


import { Hello } from "./components/Hello"; 


ReactDOM. render ( 
<Hello compiler="TypeScript" framework="React" />, 
document .getElementById("example" ) 


); 


我 们 仅仅 将 Hello 组 件 导 入 index.tsx 9 注意 ， 不 同 于 "react" 或 "react- 
dom" ， 我 们 使 用 Hello.tsx 的 相对 路 径 - 这 很 重要 。 如 果 不 这 样 做 ， 
TypeScript 只 会 尝试 在 node modules 文件 夹 里 查找 。 


我 们 还 需要 一 个 页 面 来 显示 Hello 组 件 。 在 根 目 录 proj 创建 一 个 名 
为 index.html 的 文件 ， 如 下 


<!DOCTYPE html> 


«html» 
«head» 
<meta charset="UTF-8" /» 
<title>Hello React!</title> 
</head> 
<body> 


<div id="example"></div> 


<!-- Dependencies --> 
«script src="./node_modules/react/umd/react.development. 


js"></script> 
«script src="./node modules/react-dom/umd/react-dom.deve 


lopment.js"></script> 


<!-- Main --> 
<script src=" ./dist/bundle.js"></script= 
</body> 
</html> 


需要 注意 一 点 我 们 是 从 node_modules 引入 的 文件 。 React 和 React-DOM 的 npm 

包 里 包含 了 独立 的 js 文件 ， 你 可 以 在 页 面 上 引入 它们 ， 这 里 我 们 为 了 快捷 就 直 

接 引用 了 。 可 以 随意 地 将 它们 拷贝 到 其 它 目 录 下 ， 或 者 从 CDN 上 引用 。 Facebook 
在 CND 上 提供 了 一 系列 可 用 ae ， 你 可 以 在 这 里 查看 更 多 内 容 。 


创建 一 个 webpack 配 置 文件 
在 工程 根 目 录 下 创建 一 个 webpack.config.js 文件 。 


module.exports = { 


React webpack 


entry: "./src/index.tsx", 
output: { 
filename: "bundle.js", 
path: _ dirname + "/dist" 


ty 


// Enable sourcemaps for debugging webpack's output. 
devtool: "source-map", 


resolve: { 
// Add '.ts' and '.tsx' as resolvable extensions. 
extensions. [4 tss “.tsx",. “js. "json | 


ty 


module: { 
rules: [ 
// All files with a '.ts' or '.tsx' extension will b 
e handled by 'awesome-typescript-loader'. 
( test: /N.tsx?$/, loader: "awesome-typescript-loade 


US 


// All output '.js' files will have any sourcemaps r 
e-processed by 'source-map-loader'. 
{ enforce: "pre", test: /\.js$/, loader: "source-map 
-loader" } 
] 
ty 


// When importing a module whose path matches one of the fol 
lowing, just 
// assume a corresponding global variable exists and use tha 
t instead. 
// This is important because it allows us to avoid bundling 
all of our 
// dependencies, which allows browsers to cache those librar 
ies between builds. 
externals: { 
"react": "React", 
"react-dom": "ReactDOM" 
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}; 


大 家 可 能 对 externals T FUÉ PEE ZR o 我 们 想 要 避免 把 所 有 的 React 都 放 到 一 个 
文件 里 ， 因 为 会 增加 编译 时 间 并 且 浏 览 器 还 能 够 缓存 没有 发 生 改 变 的 库 文件 。 


iz 


理想 情况 下 ， 我 们 只 需要 在 浏览 器 里 引入 React 模 块 ， 但 是 大 部 分 浏览 器 还 没有 支 
持 模块 。 因此 大 部 分 代码 库 会 把 自己 包 庄 在 一 个 单独 的 全 局 变量 内 ， 比 

如 : jQuery 或 。 这 叫做 “命名 空间 ?模式 ，webpack 也 允许 我 们 继续 使 用 通过 
这 种 方式 写 的 代码 库 。 通过 我 们 的 设置 "react": "React" ，Webpack 会 神奇 地 
将 所 有 对 "react" 的 导入 转换 成 从 React 全 局 变量 中 加 载 。 


你 可 以 在 这 里 了 解 更 多 如 何 配置 Webpack。 


整合 在 一 起 


webpack 


在 浏览 器 里 打开 index.html ， 工 程 应 该 已 经 可 以 用 了 | 你 可 以 看 到 页 面 上 显示 
着 “Hello from TypeScript and React!” 


这 篇 快速 上 手指 南 会 教 你 如 何 将 TypeScript 与 React 结 合 起 来 使 用 。 在 最 后 ， 你 将 
学 到 : 


— 


e 使 用 TypeScript 和 React 创 建 工程 

e 使 用 TSLint 进 行 代码 检查 

e 使 用 Jest 和 和 Enzyme 进行 测试 ， 以 及 
e 使 用 Redux 管 理 状态 


我 们 会 使 用 create-react-app 工 具 快 速 搭建 工程 环境 。 


这 里 假设 你 已 经 在 使 用 Node.js 和 npm。 并 且 已 经 了 解 了 React 的 基础 知识 。 


安装 create-react-app 


我 们 之 所 以 使 用 create-react-app 是 因为 它 能 够 为 React 工 程 设 置 一 些 有 效 的 工具 和 
权威 的 默认 参数 。 它 仅仅 是 一 个 用 来 搭建 React 工 程 的 命令 行 工 具 而 已 。 


npm install -g create-react-app 


创建 新 工程 
让 我 们 首先 创建 一 个 叫做 my-app 的 新 工程 : 


create-react-app my-app --scripts-version=react-scripts-ts 


react-scripts-ts 是 一 系列 适配器 ， 它 利用 标准 的 create-react-app 工 程 管 道 并 把 
TypeScript 混 入 进来 。 


此 时 的 工程 结构 应 如 下 所 示 : 


my-app/ 

| .gitignore 

— node modules/ 
~ public/ 


k src/ 
Ime 


— package. json 
~ tsconfig.json 
L- tslint.json 


e tsconfig.json 包含 了 工程 里 TypeScript 特 定 的 选项 。 

e tslint.json 保存 了 要 使 用 的 代码 检查 器 的 设置 ，TSLint。 

e package.json 包含 了 依赖 ， 还 有 一 些 命令 的 快捷 方式 ， 如 测试 命令 ， 预 览 
命令 和 发 布 应 用 的 命令 。 

e public 包含 了 静态 资源 如 HTML 页 面 或 图 片 。 除 了 index.html 文件 外 ， 其 
它 的 文件 都 可 以 删除 。 

e src 包含 了 TypeScript 和 CSS 源 码 。 index.tsx 是 强制 使 用 的 入 口 文 件 。 


A- c 

运行 工程 

通过 下 面 的 方式 即 可 轻松 地 运行 这 个 工程 。 
npm run start 


它 会 执行 package.json 里 面 指定 的 start 命令 ， 并 且 会 启动 一 个 服务 器 ， 当 我 
们 保存 文件 时 还 会 自动 刷新 页 面 。 通常 这 个 服务 器 的 地 址 
是 http://localhost:3000 ， 页 面 应 用 会 被 自动 地 打开 。 


它 会 保持 监听 以 方便 我 们 快速 地 预览 改动 。 


测试 工程 


测试 也 仅仅 是 一 行 命令 的 事 儿 : 


npm run test 


这 个 命令 会 运行 Jest， 一 个 非常 好 用 的 测试 工具 ， 它 会 运行 所 有 扩展 名 

是 .test.ts 或 .spec.ts 的 文件 。 好比 是 npm run start 命令 ， 当 检测 到 有 
改动 的 时 候 Jest 会 自动 地 运行 。 如 果 喜 欢 的 话 ， 你 还 可 以 同时 运行 npm run 
start 和 npm run test ， 这 样 你 就 可 以 在 预览 的 同时 进行 测试 。 


生成 生产 环境 的 构建 版 本 


在 使 用 nom run start 运行 工程 的 时 候 ， 我 们 并 没有 生成 一 个 优化 过 的 版 本 。 i 
常 我 们 想 给 用 户 一 个 运行 的 尽 可 能 快 并 在 体积 上 尽 可 能 小 的 代码 。 像 压 缩 这 样 的 优 
化 方法 可 以 做 到 这 一 点 ， 但 是 总 是 要 耗费 更 多 的 时 间 。 我 们 把 这 样 的 构建 版 本 称 
做 “生产 环境 "版 本 (与 开发 版 本 相对 ) 。 


要 执行 生产 环境 的 构建 ， 可 以 运行 如 下 命令 : 


npm run build 


这 会 相应 地 创建 优化 过 的 JS 和 CSS 文 
件 ， ./build/static/js 和 ./build/static/css ° 


大 多 数 情 况 下 你 不 需要 生成 生产 环境 的 构建 版 本 ， 但 它 可 以 帮助 你 衡量 应 用 最 终 版 
本 的 体积 大 小 。 


创建 一 个 组 件 


下 面 我 们 将 要 创建 一 个 Hello 组 件 。 这 个 组 件 接收 任意 一 个 我 们 想 对 之 打招呼 的 
AF (我 们 把 它 叫 做 name ) ， 并 且 有 一 个 可 选 数量 的 感叹 号 做 为 结尾 (38 


过 enthusiasmLevel ) ° 


若 我 们 这 样 写 «Hello name="Daniel" enthusiasmLevel={3} /> ， 这 个 组 件 大 
Bia mw <div>Hello Daniel!!!</div> ° 如 果 没 指定 enthusiasmLevel * 
组 件 将 默认 显示 一 个 感叹 号 。 若 enthusiasmLevel A 0 或 负 值 将 抛 出 一 个 错 


^u 
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下 面 来 写 一 下 Hello.tsx 


// src/components/Hello.tsx 
import * as React from 'react'; 


export interface Props { 
name: string; 
enthusiasmLevel?: number; 


function Hello({ name, enthusiasmLevel = 1 }: Props) { 
if (enthusiasmLevel <= 0) { 
throw new Error('You could be a little more enthusiastic. :D 
'); 
} 


return ( 
<div className="hello"> 
<div className="greeting"> 
Hello {name + getExclamationMarks(enthusiasmLevel ) } 
</div> 
</div> 


): 


export default Hello; 


// helpers 


function getExclamationMarks(numChars: number) { 
return Array(numChars + 1).join('!'); 


注意 我 们 定义 了 一 个 类 型 Props ， 它 指 定 了 我 们 组 件 要 用 到 的 属性 。 name xh 
SO HA string 类 型 ， 同 时 enthusiasmLevel 是 可 选 的 且 为 number 类 型 
(你 可 以 通过 名 字 后 面 加 ? 为 指定 可 选 参数 ) © 


我 们 创建 了 一 个 无 状态 的 函数 式 组 件 〈Stateless Functional Components ， 
SFC) Hello 。 具体 来 讨 ，Hello 是 一 个 函数 ， 接 收 一 个 Props 对 象 并 拆 解 
它 。 如 果 Props 对 象 里 没有 设置 enthusiasmLevel ， 黑 认 值 为 1 ° 


使 用 函数 是 React 中 定义 组 件 的 两 种 方式 之 一 。 如 果 你 喜欢 的 话 ， 也 可 以 通过 类 的 
方式 定义 : 


class Hello extends React.Component<Props, object» { 


render() ( 
const ( name, enthusiasmLevel - 1 j - this.props; 


if (enthusiasmLevel «- 0) ( 
throw new Error('You could be a little more enthusiastic. 


Sys 
} 
return ( 
<div className="hello"> 
<div className="greeting"> 
Hello {name + getExclamationMarks(enthusiasmLevel)} 
</div> 
</div> 
); 
} 
} 


妆 我 们 的 组 件 具有 某 些 状态 的 时 候 ， 使 用 类 的 方式 是 很 有 用 处 的 。 但 在 这 个 例子 里 
我 们 不 需要 考虑 状态 - 事实 上 ， 在 React.Component<Props, object> 我 们 把 状 
态 指定 为 了 object ， 因 此 使 用 SFC 更 简洁 。 SHA WA 
候 ， 在 表现 层 使 用 组 件 局 部 状态 比较 适合 。 针对 我 们 应 用 的 生命 周期 ， 我 们 会 审视 
应 用 是 如 何 通过 Redux 轻 松 地 管理 普通 状态 的 。 


现在 我 们 已 经 写 好 了 组 件 ， 让 我 们 仔细 看 看 index.tsx ， 把 «App /> 替换 
成 «Hello ... /> ° 


首先 我 们 在 文件 头 部 导入 它 : 


import Hello from './components/Hello'; 


后 修改 render 调用 : 


ReactDOM. render ( 
«Hello name="TypeScript" enthusiasmLevel={10} />, 
document.getElementById('root') as HTMLElement 


): 


类 型 断言 


里 还 有 一 点 要 指出 ， 就 是 最 后 一 行 document.getElementById('root') as 
HTMLElement ° 这 个 语法 叫做 类 型 断言 ， Kyu cel 当 你 比 类 型 检查 器 更 
清楚 一 个 表达 式 的 类 型 的 时 候 ， 你 可 以 通过 这 种 方式 通知 TypeScript 。 


这 里 ， 我 们 之 所 以 这 么 做 是 因为 getElementById 的 返回 值 类 型 是 HTMLElement 
| null ° 简单 地 说 ， getElementById 返回 null 是 当 无 法 找 对 对 应 id TH 
的 时 候 。 我们 假设 getElementById 总 是 成 功 的 ， 因 此 我 们 要 使 用 as 语法 告诉 
TypeScript 这 点 。 

TypeScript 还 有 一 种 感叹 号 ( 1 ) 结尾 的 语法 ， 它 会 从 前 面 的 表达 式 里 移 


除 null 和 undefined 。 所 以 我 们 也 可 以 写 
成 document.getElementById('root')! ， 但 在 这 里 我 们 想 写 的 更 清楚 些 。 


(oy 
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通过 我 们 的 设置 为 一 个 组 件 添加 样式 很 容易 。 若 要 设置 Hello 组 件 的 样式 ， 我 们 
可 以 创建 这 样 一 个 CSS 文 件 src/components/Hello.css ° 


.hello { 
text-align: center; 
margin: 20px; 
font-size: 48px; 
font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif 


.hello button { 
margin-left: 25px; 
margin-right: 25px; 
font-size: 40px; 
min-width: 50px; 


create-react-app 包含 的 工具 (Webpack 和 一 些 加 载 器 ) 允许 我 们 导入 样式 表 
文件 。 当 我 们 构建 应 用 的 时 候 ， 所 有 导入 的 ,css 文件 会 被 拼接 成 一 个 输出 文 
件 。 因 此 在 src/components/Hello.tsx ， 我 们 需要 添加 如 下 导入 语 钉 。 


import *./Hello.css’ ; 


使 用 Jest 编 写 测 试 
如 果 你 没 使 用 过 Jest， 你 可 能 先 要 把 它 安 装 为 开发 依赖 项 。 


npm install -D jest jest-cli jest-config 


我 们 对 Hello 组 件 有 一 些 假设 。 让 我 们 在 此 重申 一 下 : 


e 当 这 样 写 <Hello name="Daniel" enthusiasmLevel={3} /> 时 ， 组 件 
应 被 泻 染 成 <div>Hello Daniel!!!«/div» ° 
e 若 未 指定 enthusiasmLevel ， 组 件 应 默认 显示 一 个 感叹 号 。 


e 若 enthusiasmLevel 为 0 或 负 值 ， 它 应 抛 出 一 个 错误 。 


我 们 将 针对 这 些 需求 为 组 件 写 一 些 注释 。 


但 首先 ， 我 们 要 安装 Enzyme。 Enzyme 是 React 生 态 系统 里 一 个 通用 工具 ， 它 方便 
了 针对 组 件 的 行为 编写 测试 。 默 认 地 ， 我 们 的 应 用 包含 了 一 个 叫做 jsdom 的 库 ， 它 
允许 我 们 模拟 DOM 以 及 在 非 浏览 器 的 环境 下 测试 运行 时 的 行为 。Enzyme 与 此 类 
似 ， 但 是 是 基于 jsdom 的 ， 并 且 方 便 我 们 查询 组 件 。 


让 我 们 把 它 安装 为 开发 依赖 项 。 


npm install -D enzyme @types/enzyme enzyme-adapter-react-16 @typ 
es/enzyme-adapter-react-16 


如 果 你 的 react 版 本 低 于 15.5.0， 还 需 安 装 如 下 


npm install -D react-addons-test-utils 


注意 我 们 同时 安装 了 enzyme 和 @types/enzyme * enzyme 包 指 的 是 包含 了 实 
际 运 行 的 JavaScript 代 码 包 ， 而 @types/enzyme 则 包含 了 声明 文件 ( .d.ts X 
TF) 的 包 ， 以 便 TypeScript 能 够 了 解 该 如 何 使 用 Enzyme 。 你 可 以 在 这 里 了 解 更 多 
关于 @types 包 的 信息 。 

我 们 还 需要 安装 enzyme-adapter 和 react-addons-test-utils 。 它们 是 使 
gg py 器 是 必须 的 ， 而 后 者 若 采 用 的 
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现在 我 们 已 经 设置 好 了 Enzyme， 下 面 开 始 编写 测试 | 先 创建 一 个 文 
TF src/components/Hello.test.tsx ， 与 先前 的 Hello.tsx 文件 放 在 一 


// src/components/Hello.test.tsx 


import * as React from 'react'; 

import * as enzyme from 'enzyme'; 

import * as Adapter from 'enzyme-adapter-react-16'; 
import Hello from './Hello'; 


enzyme.configure(( adapter: new Adapter() }); 
it('renders the correct text when no enthusiasm level is given', 


() => 


const hello = enzyme.shallow(<Hello name='Daniel' />); 


expect (hello. find(".greeting").text()).toEqual('Hello Daniel!' 


) 
3); 


it('renders the correct text with an explicit enthusiasm of 1', 
() => { 
const hello = enzyme.shallow(<Hello name='Daniel' enthusiasmLe 
vel={1}/>); 
expect(hello.find(".greeting").text()).toEqual('Hello Daniel! ' 
) 
3); 


it('renders the correct text with an explicit enthusiasm level o 
rey OQ = 1 

const hello = enzyme.shallow(<Hello name='Daniel' enthusiasmLe 
vel-(5) />); 

expect (hello. find(".greeting").text()).toEqual('Hello Daniel! ! 
LT) 


3); 


it('throws when the enthusiasm level is 0', () => ( 
expect(() => 1 
enzyme.shallow(«Hello name='Daniel' enthusiasmLevel={0} /»); 
}).toThrow(); 


3); 
it('throws when the enthusiasm level is negative', () => { 
expect(() => { 


enzyme.shallow(«Hello name='Daniel' enthusiasmLevel-(-1) />) 


}).toThrow(); 
3): 


这 些 测试 都 十 分 基础 ， 但 你 可 以 从 中 得 到 启发 。 


添加 state 管 理 


到 此 为 止 ， 如 果 你 使 用 React 的 目的 是 只 获取 一 次 数据 并 显示 ， 那 么 你 已 经 完 
了 。 但 是 如 果 你 想 开 发 一 个 可 以 交互 的 应 用 ， 那 么 你 需要 添加 state 管 理 。 


state 管 理 概述 


React 本 身 就 是 一 个 适合 于 创建 可 组 合 型 视图 的 库 。 但 是 ，React 并 没有 任何 在 应 
用 间 同 步 数据 的 功能 。 就 React 组 件 而 言 ， 数 据 是 通过 每 个 元 素 上 指定 的 props 向 子 
元 素 传 递 。 


因为 React 本 身 并 没有 提供 内 置 的 state 管 理 功 能 ，React 社 区 选择 了 Redux 和 MobX 
Eo 


Redux 依 靠 一 个 统一 且 不 可 变 的 数据 存储 来 同步 数据 ， 并 且 更 新 那里 的 数据 时 会 触 
发 应 用 的 更 新 泻 染 。 state 的 更 新 是 以 一 种 不 可 变 的 方式 进行 ， 它 会 发 布 一 条 明确 
的 action 消 息 ， 这 个 消息 必须 被 reducer 函 数 处 理 。 由 于 使 用 了 这 样 明确 的 方式 ， 很 


容易 弄 清楚 一 个 action 是 如 何 影响 程序 的 state 。 


MobX 借 助 于 函数 式 响应 型 模式 ，state 被 包装 在 了 可 观察 对 和 象 里 ， 并 通过 props 传 
北 。 通 过 将 state 标 记 为 可 观察 的 ， 即 可 在 所 有 观察 者 之 间 保 持 state 的 同步 性 。 另 
一 个 好 处 是 ， 这 个 库 已 经 使 用 TypeScript 实 现 了 。 


这 两 者 各 有 优 缺 点 。 但 Redux 使 用 得 更 广泛 ， 因 此 在 这 篇 教程 里 ， 我 们 主要 看 如 何 
使 用 Redux ; 但 是 也 鼓励 大 家 两 者 都 去 了 解 一 下 。 


后 面 的 小 节 学 习 曲 线 比 较 陡 。 因此 强烈 建议 大 家 先 去 熟悉 一 下 Redux。 


x i& actions 


只 有 当 应 用 里 的 state 会 改变 的 时 候 ， 我 们 才 需 要 去 添加 Redux。 我 们 需要 一 个 
action 的 来 源 ， 它 将 触发 改变 。 它 可 以 是 一 个 定时 器 或 者 UI 上 的 一 个 按钮 。 


为 此 ， 我 们 将 增加 两 个 按钮 来 控制 Hello 组 件 的 感叹 级 别 。 


安装 Redux 


安装 redux 和 react-redux 以 及 它们 的 类 型 文件 做 为 依赖 。 


npm install -S redux react-redux @types/react - redux 


这 里 我 们 不 需要 安装 Otypes/redux ， 因 为 Redux 已 经 自 带 了 声明 文件 
( ,dts 文件 ) 。 
定义 应 用 的 状态 


我 们 需要 定义 Redux 保 存 的 state 的 结构 。 创 建 src/types/index.tsx 文件 ， 它 
保存 了 类 型 的 定义 ， 我 们 在 整个 程序 里 都 可 能 用 到 。 


// src/types/index.tsx 
export interface StoreState { 


languageName: string; 
enthusiasmLevel: number; 


这 里 我 们 想 让 languageName 表示 应 用 使 用 的 编程 语言 (例如 ，TypeScript 或 者 
JavaScript) ， enthusiasmLevel 是 可 变 的 。 在 写 我 们 的 第 一 个 容器 的 时 候 ， 就 
会 明白 为 什么 要 令 state 与 props 稍 有 不 同 。 
二 加 actions 
下 面 我 们 创建 这 个 应 用 将 要 响应 的 消息 类 型 ， src/constants/index.tsx ° 

// src/constants/index.tsx 

export const INCREMENT ENTHUSIASM - 'INCREMENT ENTHUSIASM'; 


export type INCREMENT ENTHUSIASM - typeof INCREMENT ENTHUSIASM; 


export const DECREMENT ENTHUSIASM = 'DECREMENT ENTHUSIASM'; 
export type DECREMENT ENTHUSIASM - typeof DECREMENT ENTHUSIASM; 


这 里 的 const / type 模式 允许 我 们 以 容易 访问 和 重 构 的 方式 使 用 TypeScript 的 字 
符 串 字面 量 类 型 。 
接 下 来 ， 我 们 创建 一 些 actions 以 及 创建 这 些 actions 的 苑 


数 ， src/actions/index.tsx ° 


import * as constants from '../constants' 


export interface IncrementEnthusiasm { 
type: constants. INCREMENT_ENTHUSIASM; 


export interface DecrementEnthusiasm { 
type: constants.DECREMENT ENTHUSIASM; 


export type EnthusiasmAction - IncrementEnthusiasm | DecrementEn 
thusiasm; 


export function incrementEnthusiasm(): IncrementEnthusiasm { 
return { 
type: constants.INCREMENT ENTHUSIASM 


export function decrementEnthusiasm(): DecrementEnthusiasm { 
return { 
type: constants.DECREMENT ENTHUSIASM 


我 们 创建 了 两 个 类 型 ， 它 们 负责 增加 操作 和 减少 操作 的 行为 。 我 们 还 定义 了 一 个 类 
型 ( EnthusiasmAction ) ， 它 描述 了 哪些 action 是 可 以 增加 或 减少 的 。 最后， 
我 们 定义 了 两 个 函数 用 来 创建 实际 的 actions 。 


这 里 有 一 些 清晰 的 模版 ， 你 可 以 参考 类 似 redux-actions 的 库 。 


添加 reducer 


现在 我 们 可 以 开始 写 第 一 个 reducer 了 ! Reducers 是 函数 ， 它 们 负责 生成 应 用 state 
的 拷贝 使 之 产生 变化 ， 但 它 并 没有 副作用 。 它们 是 一 种 纯 隙 数 。 


我 们 的 reducer 将 放 在 src/reducers/index.tsx 文件 里 。 它 的 功能 是 保证 增加 
操作 会 让 感叹 级 别 加 1， 减 少 操作 则 要 将 感叹 级 别 减 1， 但 是 这 个 级 别 永远 不 能 小 于 
1 。 


// src/reducers/index.tsx 


import ( EnthusiasmAction ) from '../actions'; 

import { StoreState } from '../types/index'; 

import { INCREMENT ENTHUSIASM, DECREMENT ENTHUSIASM } from '../c 
onstants/index'; 


export function enthusiasm(state: StoreState, action: Enthusiasm 
Action): StoreState { 
switch (action.type) ( 
case INCREMENT ENTHUSIASM: 


return ( ...state, enthusiasmLevel: state.enthusiasmLevel 
"o 
case DECREMENT ENTHUSIASM: 
return ( ...state, enthusiasmLevel: Math.max(1, state.enth 
usiasmLevel - 1) Y; 
} 
return state; 


注意 我 们 使 用 了 对 象 展 开 ( ...state ) ， 当 替换 enthusiasmLevel 时 ， 它 可 以 
IRA ATA Mo A enthusiasmLevel 属性 放 在 末尾 是 十 分 关键 的 ， 否 则 它 将 
被 日 的 状态 覆盖 。 


你 可 能 想 要 对 reducer 写 一 些 测试 。 因为 reducers 是 纯 函 数 ， 它 们 可 以 传 入 任意 的 
数据 。 针对 每 个 输入 ， 可 以 测试 reducers 生 成 的 新 的 状态 。 可 以 考虑 使 用 Jest 的 
toEqual 方 法 。 


创建 容器 


在 使 用 Redux 时 ， 我 们 常常 要 创建 组 件 和 容器 。 组 件 是 数据 无 关 的 ， 且 工作 在 表现 
层 。 容 器 通常 包 衰 组 件 及 其 使 用 的 数据 ， 用 以 显示 和 修改 状态 。 你 可 以 在 这 里 阅 
读 更 多 关于 这 个 概念 的 细节 : Dan Abramov 写 的 表现 层 的 容器 组 件 。 


现在 我 们 修改 src/components/Hello.tsx ， 让 它 可 以 修改 状态 。 我 们 将 添加 两 
个 可 选 的 回调 属性 到 Props ， 它 们 分 别 是 onIncrement 和 onDecrement 


export interface Props { 
name: string; 
enthusiasmLevel?: number; 
onIncrement?: () => void; 
onDecrement?: () => void; 


然后 将 这 两 个 回调 绑 定 到 两 个 新 按钮 上 ， 将 按钮 添加 到 我 们 的 组 件 里 。 


function Hello({ name, enthusiasmLevel = 1, onIncrement, onDecre 
ment }: Props) { 
if (enthusiasmLevel <= 0) { 
throw new Error('You could be a little more enthusiastic. :D 


D 


} 
return ( 
<div className="hello"> 
<div className="greeting"> 
Hello {name + getExclamationMarks(enthusiasmLevel ) } 
</div> 
<div> 
«button onClick={onDecrement }>-</button> 
«button onClick={onIncrement }>+</button> 
</div> 
</div> 
); 
} 


通常 情况 下 ， 我 们 应 该 给 onIncrement 和 onDecrement 写 一 些 测试 ， 它 们 是 在 
各 自 的 按钮 被 点 击 时 调用 。 试 一 试 以 便 掌 握 编 写 测 试 的 窍门 。 


现在 我 们 的 组 件 更 新 好 了 ， 可 以 把 它 放 在 一 个 容器 里 了 o 让 我 们 来 创建 一 个 文 
fF src/containers/Hello.tsx ， 在 开始 的 地 方 使 用 下 列 导 入 语句 。 


import Hello from '../components/Hello'; 

import ^ as actions from '../actions/'; 

import { StoreState } from '../types/index'; 
import { connect, Dispatch } from 'react-redux'; 


两 个 关键 点 是 初始 的 Hello 组 件 和 react-redux 的 connect 42° connect 可 
以 将 我 们 的 Hello 组 件 转换 成 一 个 容器 ， 通 过 以 下 两 个 函数 : 


e mapStateToProps 将 当前 store 里 的 数据 以 我 们 的 组 件 需要 的 形式 传递 到 组 
件 。 

e mapDispatchToProps 利用 dispatch 元 数 ， 创 建 回调 props 将 actions 送 到 
store ° 


回想 一 下 ， 我 们 的 应 用 包含 两 个 属性 : languageName 和 enthusiasmLevel ° 
我 们 的 Hello 组 件 ， 硕 望 得 到 一 个 name 和 一 个 enthusiasmLevel 。 
mapStateToProps 会 从 store 得 到 相应 的 数据 ， 如 果 需 要 的 话 将 针对 组 件 的 props 
调整 它 。 下 面 让 我 们 继续 往 下 写 。 


export function mapStateToProps({ enthusiasmLevel, languageName 
}: StoreState) { 
return { 
enthusiasmLevel, 
name: languageName, 


注意 mapstateToProps 仅 创 建 了 Hello 组 件 需要 的 四 个 属性 中 的 两 个 。 我 们 还 
想 要 传 入 onIncrement 和 onDecrement 回调 函数 。 mapDispatchToProps 是 
一 个 函数 ， 它 需要 传 入 一 个 调度 函数 。 这 个 调度 函数 可 以 将 actions 传 入 store 来 触 
发 更 新 ， 因 此 我 们 可 以 创建 一 对 回调 函数 ， 它 们 会 在 需要 的 时 候 调 用 调度 函数 。 


export function mapDispatchToProps(dispatch: Dispatch<actions.En 
thusiasmAction>) { 
return { 
onIncrement: () => dispatch(actions.incrementEnthusiasm()), 
onDecrement: () => dispatch(actions.decrementEnthusiasm()), 


最 后 ， 我 们 可 以 调用 connect F ° connect 首先 会 接 
收 mapStateToProps 和 mapDispatchToProps ， 然 后 返回 另 一 个 函数 ， 我 们 用 
它 来 包 衰 我 们 的 组 件 。 最 终 的 容器 是 通过 下 面 的 代码 定义 的 : 


export default connect(mapStateToProps, mapDispatchToProps)(Hell 
0); 


现在 ， 我 们 的 文件 应 该 是 下 面 这 个 样子 : 


// src/containers/Hello.tsx 


import Hello from '../components/Hello'; 

import * as actions from '../actions/'; 

import { StoreState } from '../types/index'; 
import { connect, Dispatch } from 'react-redux'; 


export function mapStateToProps({ enthusiasmLevel, languageName 
}: StoreState) { 
return { 
enthusiasmLevel, 
name: languageName, 


export function mapDispatchToProps(dispatch: Dispatch<actions.En 
thusiasmAction>) { 
return { 
onIncrement: () => dispatch(actions.incrementEnthusiasm()), 
onDecrement: () => dispatch(actions.decrementEnthusiasm()), 


export default connect(mapStateToProps, mapDispatchToProps) (Hell 
0); 


创建 store 


让 我 们 回 到 src/index.tsx 。 要 把 所 有 的 东西 合 到 一 起 ， 我 们 需要 创建 一 个 带 初 
始 状 态 的 store， 并 用 我 们 所 有 的 reducers 来 设置 它 。 


import { createStore } from 'redux'; 
import { enthusiasm } from './reducers/index'; 
import { StoreState } from './types/index'; 


const store = createStore<StoreState>(enthusiasm, { 
enthusiasmLevel: i, 


languageName: 'TypeScript', 
3); 


store 可 能 正如 你 想 的 那样 ， 它 是 我 们 应 用 全 局 状态 的 核心 store。 


接 下 来 ， 我 们 将 要 用 ./src/containers/Hello 来 包 


XX ./src/components/Hello ， 然 后 使 用 react-redux 的 Provider 将 props 与 容 


器 连通 起 来 。 我们 将 导入 它们 : 


import Hello from './containers/Hello'; 
import { Provider } from 'react-redux'; 


将 store VA Provider 的 属性 形式 传 入 : 


ReactDOM. render ( 


<Provider store={store}> 
<Hello /> 
</Provider>, 


document.getElementById('root') as HTMLElement 
); 


注意 ， Hello 不 再 需要 props 了， 因为 我 们 使 用 了 connect HRA 6, XA 
的 Hello 组 件 的 props 适 配 了 应 用 的 状态 。 


退出 


如 果 你 发 现 create-react-app 使 一 些 自 定 义 设 置 变 得 困难 ， 那 么 你 就 可 以 选择 不 使 用 
它 ， 使 用 你 需要 配置 。 比如， 你 要 添加 一 个 Webpack 插 件 ， 你 就 可 以 利用 create- 
react-app 提 供 的 “eject" 功 能 。 


(s 
oN 


npm run eject 


这 样 就 可 以 了 | 


你 要 注意 ， 在 运行 eject 前 最 好 保存 你 的 代码 。 你 不 能 撤销 eject 命 令 ， 因 此 退出 操 
作 是 永久 性 的 除非 你 从 一 个 运行 eject 前 的 提交 来 恢复 工程 。 


下 
create-reactrapp 带 有 很 多 很 棒 的 功能 。 它们 的 大 多 数 都 在 我 们 工程 生成 
的 README .md 里 面 有 记录 ， 所 以 可 以 简单 阅读 一 下 。 


如 果 你 想 学 习 更 多 关于 Redux 的 知识 ， 你 可 以 前 往 官方 站 点 查看 文档 。 同样 

的 ，MobX 官 方 站 点 。 

如 果 你 想 要 在 茶 个 时 间 点 eject， 你 需要 了 解 再 多 关于 Webpack 的 知识 。 你 可 以 查 
看 React & Webpack 教 程 。 


有 时 候 你 需要 路 由 功能 。 已 经 有 一 些 解 决 方案 了 ， 但 是 对 于 Redux 工 程 来 讲 react- 
router 是 最 流行 的 ， 并 经 常 与 react-router-redux 联 合 使 用 。 


即将 到 来 的 Angular 2 框架 是 使 用 TypeScript 开 发 的 。 因 此 Angular 和 TypeScript 一 
起 使 用 非常 简单 方便 。 Angular 团 队 也 在 其 文档 里 把 TypeScript 视 为 一 等 公民 。 

正 因为 这 样 ， 你 总 是 可 以 在 Angular 2 官网 (或 Angular 2 官网 中 文 版 ) 里 查看 到 最 新 的 
结合 使 用 Angular 和 TypeScript 的 参考 文档 。 在 这 里 查看 快速 上 手指 南 ， 现 在 就 开 
始 学 习 吧 | 


TypeScript4 FEF AE Po 它 从 JavaScript 生 态 系统 和 大 量 现存 的 JavaScript 而 
来 。 将 JavaScript 代 码 转换 成 TypeScript 虽 乏味 却 不 是 难事 。 接 下 来 这 篇 教程 将 教 
你 怎么 做 。 在 开始 转换 TypeScript 之 前 ， 我 们 假设 你 已 经 理解 了 足够 多 本 手册 里 的 
内 容 。 


如 果 你 打算 要 转换 一 个 React 工 程 ， 推 荐 你 先 阅 读 React 转 换 指 南 。 


it a El RK 


如 果 你 在 写 纯 JavaScript， 你 大 概 是 想 直 接 运行 这 i o ， 这些 文件 存 
在 于 src > lib 或 dist 目录 里 ， 它 们 可 以 按照 预想 运行 。 


若 如 此 ， 那 么 你 写 的 纯 JavaScript 文 件 将 做 为 TypeScript 的 输入 ， 你 将 要 运行 的 是 
TypeScript 的 输出 。 在 从 JS 到 TS 的 转换 过 程 中 ， 我 们 会 分 离 输入 文件 以 防 
TypeScript 履 盖 它 们 。 你 也 可 以 指定 输出 目录 。 


你 可 能 还 需要 对 JavaScript 做 一 些 中 间 处 理 ， 比 如 合并 或 经 过 Babel 再 次 编译 。 在 
这 种 情况 下 ， 你 应 该 已 经 有 了 如 下 的 目录 结构 。 


那么 现在 ， 我 们 假设 你 已 经 设置 了 这 样 的 目录 结构 : 


projectRoot 


| 一 src 
e 
EE 


— built 


L— tsconfig.json 


果 你 在 src 目录 外 还 有 tests CHK? PAA src 里 可 以 有 一 
个 tsconfig.json 文件 ， 在 tests 里 还 可 以 有 一 个 。 


书写 配置 文件 


een tsconfig.json 文件 管理 工程 配置 ， 例 如 你 想 包含 哪些 文件 和 进 
行 哪些 检查 。 让 我 们 先 创建 一 个 简单 的 工程 配置 文件 : 


"compilerOptions": { 
ou Da :0 DULL 
"allowJs": true, 


"target": "es5" 
17 
"include": [ 

S CAA fake 
] 


这 里 我 们 为 TypeScript 设 置 了 一 些 东 西 : 


. 读 取 所 有 可 识别 的 src 目录 下 的 文件 (通过 include ) ° 

.接受 JavaScript 做 为 输入 (通过 allowJs ) ° 

.生成 的 所 有 文件 放 在 built 目录 下 (通过 outDir ) ° 

. 将 JavaScript 代 码 降 级 到 低 版 本 比如 ECMAScript 5 (通过 target ) ° 


BOND 一 


现在 ， 如 果 你 在 工程 根 目 录 下 运行 tsc ， 就 可 以 在 built 目录 下 看 到 生成 的 文 
件 。 built 下 的 文件 应 该 与 src 下 的 文件 相同 。 现在 你 的 工程 里 的 TypeScript 
已 经 可 以 工作 了 。 


早期 收益 


现在 你 已 经 可 以 看 到 TypeScript 带 来 的 好 处 ， 它 能 帮助 我 们 理解 当前 工程 。 如果 你 
打开 像 VS Code X Visual Studio 这 样 的 编译 器 ， 你 就 能 使 用 像 自动 补 全 这 样 的 工 
具 。 你 还 可 以 配置 如 下 的 选 E cie 


e noImplicitReturns Miku Rick KE GR UM o 
e noFallthroughCasesInSwitch 会 防止 在 switch 代码 块 里 的 两 
个 case ZA Ei» break 语句 。 


TypeScript 还 能 发 现 那些 执行 不 到 的 代码 和 标签 ， 你 可 以 通过 设 
置 allowUnreachableCode 和 allowUnusedLabels 选项 来 禁用 。 


与 构建 工具 进行 集成 


在 你 的 构建 管道 中 可 能 包含 多 个 步骤 。 比如 为 每 个 文件 添加 一 些 内容 。 每 种 工具 
的 使 用 方法 都 是 不 同 的 ， 我 们 会 尽 可 能 的 包涵 主流 的 工具 。 


Gulp 


ho RAK AE 18 AT XE Gulp > RT CAA — HA k Tit A Gulp 48 @TypeScript# 5 % JL 
构建 工具 Browserify，Babelify 和 Uglify 进 行 集成 的 教程 。 请 阅读 这 篇 教程 。 


Webpack 


Webpack 集 成 非常 简单 。 你 可 以 使 用 awesome-typescript-loader ， 它 是 一 个 
TypeScript 的 加 载 器 ， 结 合 source-map-loader 方便 调试 。 运行 : 


npm install awesome-typescript-loader source-map-loader 


并 将 下 面 的 选项 合并 到 你 的 webpack.config.js 文件 里 : 


JJ JavaScripti£ 4 2] TypeScript 


module.exports - ( 


entry: “./sre/index. ts", 
output: { 
filename: "./dist/bundle.js", 


ty 


// Enable sourcemaps for debugging webpack's output. 
devtool: "source-map", 


resolve: { 
// Add '.ts' and '.tsx' as resolvable extensions. 
extensions: ["", ".webpack.js", ".web.js", ".ts", 


DSe] 

tr 

module: { 
loaders: [ 


// All files with a '.ts' or '.tsx' extension will b 


e handled by 'awesome-typescript-loader'. 


rt } 


{ test: /\.tsx?$/, loader: "awesome-typescript-loade 


], 


preLoaders: [ 


" F ESX" 


// All output '.js' files will have any sourcemaps r 


e-processed by 'source-map-loader'. 


iz 


Liz 
之 前 


{ test: /\.js$/, loader: "source-map-loader" } 


] 
}, 
// Other options... 
意 的 是 ， awesome-typescript-loader 必须 在 其 它 处 理 .js 文件 的 加 载 
运行 


这 与 另 一 个 TypeScript 的 Webpack 加 载 器 ts-loader 是 一 样 的 。 你 可 以 到 这 里 了 解 
者 之 间 的 差别 。 


ex 


两 


93 


你 可 以 在 React 和 Webpack 教 程 里 找到 使 用 Webpack 的 例子 。 


转换 到 TypeScript 文 件 


到 目前 为 止 ， 你 已 经 做 好 了 使 用 TypeScript 文 件 的 准备 。 第 一 步 ， 将 .js 文件 重 
命名 为 ,ts 文件 。 如 果 你 使 用 了 JSX， 则 重 命名 为 ,tsx 文件 。 


第 一 步 达 成 ? KI T! 你 已 经 成 功 地 将 一 个 文件 从 JavaScript 转 换 成 了 TypeScriptl 


当然 了 ， 你 可 能 感觉 哪里 不 对 劲 几 。 如 果 你 在 支持 TypeScript 的 编辑 器 〈 或 运 
ff tsc --pretty ) 里 打开 了 那个 文件 ， 你 可 能 会 看 到 有 些 行 上 有 红色 的 波浪 
Boo 你 可 以 把 它们 当做 在 Microsoft Word 里 看 到 的 红色 波浪 线 一 样 。 但 是 
TypeScript 仍 然 会 编译 你 的 代码 ， 就 好 比 Word 还 是 允许 你 打印 你 的 文档 一 样 。 


如 果 对 你 来 说 这 种 行为 太 随 便 了 ， 你 可 以 让 它 变 得 严格 些 。 如 果 ， 你 不 想 在 发 生 错 
误 的 时 候 ，TypeScript 还 会 被 编译 成 JavaScript， 你 可 以 使 用 noEmitonError 选 
项 。 从 某 种 意义 上 来 讲 ，TypeScript 具 有 一 个 调整 它 的 严格 性 的 刻度 盘 ， 你 可 以 将 
指针 拔 动 到 你 想 要 的 位 置 。 


如 果 你 计划 使 用 可 用 的 高 度 严 格 的 设置 ， 最 好 现在 就 启用 它们 (查看 启用 严格 检 
查 ) o 比如 ， 如 果 你 不 想 让 TypeScript 将 没有 明确 指定 的 类 型 默默 地 推断 

为 any 类 型 ， 可 以 在 修改 文件 之 前 启用 normplicitAny 。 你 可 能 会 觉得 这 有 些 
过 度 严 格 ， 但 是 长 期 收益 很 快 就 能 显现 出 来 。 


去 除 错 误 


我 们 提 到 过 ， 若 不 出 所 料 ， 在 转换 后 将 会 看 到 错误 信息 。 重要 的 是 我 们 要 逐一 的 查 
看 它们 并 决定 如 何 处 理 。 通常 这 些 都 是 真正 的 BUG， 但 有 时 必须 要 告诉 TypeScript 
你 要 做 的 是 什么 。 


由 模块 导入 


首先 你 可 能 会 看 到 一 些 类 似 Cannot find name 'require'. 和 Cannot find 
name 'define'. 的 错误 。 遇 到 这 种 情况 说 明 你 在 使 用 模块 。 你 仅 需 要 告诉 
TypeScript 它 们 是 存在 的 : 


// For Node/CommonJS 
declare function require(path: string): any; 


x 


// For RequireJS/AMD 
declare function define(...args: any[]): any; 


最 好 是 避免 使 用 这 些 调 用 而 改 用 TypeScript 的 导入 语法 。 


首先 ， 你 要 使 用 TypeScript 的 module 标记 来 启用 一 些 模块 系统 。 可 用 的 选项 


有 commonjs > amd ， system ，and umd ° 


如 果 代 码 里 存在 下 面 的 Node/CommonJS 代 码 : 
var foo = Pequire( noo); 
foo.doStuff(); 

或 者 下 面 的 RequireJS/AMD 代 码 : 


define(["foo"], function(foo) ( 
foo.doStuff(); 


1) 
那么 可 以 写 做 下 面 的 TypeScript 代 码 : 


import foo = require("foo"); 


foo.doStuff(); 


获取 声明 文件 


如 果 你 开始 做 转换 到 TypeScript 导 入 > 


你 可 能 会 遇 到 Cannot find module 
'foo'. 


这 样 的 错误 。 问题 出 在 没有 声明 文件 来 描述 你 的 代码 库 。 幸运 的 是 这 非常 


简单 。 如 果 TypeScript 报 她 像 是 没有 lodash 包 ， 那 你 只 需 这 样 做 


npm install -S @types/lodash 


如 果 你 没有 使 用 commonjs 模块 模块 选项 ， 那 么 训 


就 需要 将 moduleResolution 选 
项 设置 为 node 。 
， 你 应 该 就 可 以 导入 lodash 了 ， 并 且 会 获得 精确 的 自动 补 全 功能 。 


由 模块 导出 


通常 来 讲 ， 由 模块 导出 涉及 添加 属性 到 exports 或 module.exports ° 
TypeScript 允 许 你 使 用 顶级 的 导出 语句 。 比如 ， 你 要 导出 下 面 的 函数 


module.exports.feedPets = function(pets) { 


/ / naa 
那么 你 可 以 这 样 写 
export function feedPets(pets) { 


有 时 你 会 完全 重 写 导出 对 象 。 这 是 一 个 常见 模式 ， 这 会 将 模块 变 为 可 立即 调用 的 模 
块 : 


var express = require("express"); 
var app = express(); 


之 前 你 可 以 是 这 样 写 的 : 


FUnECELON, Too() 4 
"m 


j 


module.exports - foo; 


在 TypeScript 里 ， 你 可 以 使 用 export = 来 代替 。 


function foo() { 
AAA 


} 


export = foo; 


过 多 或 过 少 的 参数 


有 时 你 会 发 现 你 在 调用 一 个 具有 过 多 或 过 少 参 数 的 函数 。 通 常 ， 这 是 一 个 BUG ， 
但 在 某 些 情况 下 ， 你 可 以 声明 一 个 使 用 arguments 对 象 的 函数 而 不 需要 写 出 所 有 
参数 : 


function myCoolFunction() { 
if (arguments.length == 2 && !Array.isArray(arguments[1])) { 
var f = arguments[0]; 
var arr = arguments[1]; 
gue 


myCoolFunction(function(x) { console.log(x) }, [1, 2, 3, 4]); 
myCoolFunction(function(x) { console.log(x) }, 1, 2, 3, 4); 


这 种 情况 下 ， 我 们 需要 利用 TypeScript 的 函数 重 载 来 告诉 调用 
者 myCoolFunction HANWHA AX ° 


function myCoolFunction(f: (x: number) => void, nums: number[]): 
void; 
function myCoolFunction(f: (x: number) => void, ...nums: number[ 
]): void; 
function myCoolFunction() { 
if (arguments.length == 2 && !Array.isArray(arguments[1])) { 
var f = arguments[0]; 
var arr = arguments[1]; 
7 NTC 


AR 


我 们 为 myCoolFunction 函数 添加 了 两 个 重 载 签名 。 第 一 个 检 

查 myCoolFunction 函数 是 否 接收 一 个 函数 〈 它 又 接收 一 个 number 参数 ) 和 一 
个 number 数组 。 第 二 个 同样 是 接收 了 一 个 函数 ， 并 且 使 用 剩余 参数 

( ...nums ) 来 表示 之 后 的 其 它 所 有 参数 必须 是 number 类 型 。 


连续 添加 属性 
有 些 人 可 能 会 因为 代码 美观 性 而 喜欢 先 创建 一 个 对 象 然后 立即 添加 属性 : 


var options = {}; 
options.color = "red"; 
options.volume = 11; 


TypeScript 会 提示 你 不 能 给 color 和 volumn 赋值 ， 因 为 先前 指定 options 的 
类 型 为 {} 并 不 带 有 任何 属性 。 如 果 你 将 声明 变 成 对 象 字面 量 的 形式 将 不 会 产生 


错误 : 


let options = { 
color: "red", 
volume: 11 


你 还 可 以 定义 options 的 类 型 并 且 添 加 类 型 断言 到 对 象 字面 量 上 。 


interface Options { color: string; volume: number } 


let options = {} as Options; 
options.color = "red"; 
options.volume = 11; 


或 者 ， 你 可 以 将 options 指定 成 any 类 型 ， 这 是 最 简单 的 ， 但 也 是 获 益 最 少 
8 


any * Object ° #7 {} 


你 可 能 会 试图 使 用 object X { 来 表示 一 个 值 可 以 具有 任意 属性 ， 因 

为 Object 是 最 通用 的 类 型 。 然而 在 这 种 情况 下 any 是 趴 正 想 要 使 用 的 类 型 ， 因 
为 它 是 最 灵活 的 类 型 。 

比如 ， 有 一 个 Object 类 型 的 东西 ， 你 将 不 能 够 在 其 上 调用 tolowerCase() ° 
越 普通 意味 着 更 少 的 利用 类 型 ， 但 是 any 比较 特殊 ， 它 是 最 普通 的 类 型 但 是 允许 
你 在 上 面 做 任何 事情 。 也 就 是 说 你 可 以 在 上 面 调用 ， 构 造 它 ， 访 问 它 的 属性 等 等 


记 住 ， 当 你 使 用 any 时 ， 你 会 失去 大 多 数 TypeScript 提 供 的 错误 检查 和 编译 器 支 
持 。 


如 果 你 还 是 决定 使 用 Object de {} ， 你 应 该 选择 (poo 虽说 它们 基本 一 样 ， 但 
是 从 技术 角度 上 来 讲 {} 在 一 些 深奥 的 情况 里 比 object 更 普通 。 


尼 用 严格 检查 


TypeScript 提 供 ee 以 及 帮助 分 析 你 的 程序 。 当 你 将 代码 转换 为 
了 TypeScript 后 ， 你 可 以 启用 这 些 检查 来 帮助 你 获得 高 度 安全 性 。 


AA IAS] any 


在 某 些 情况 下 TypeScript 没 法 确定 某 些 值 的 类 型 。 那 么 TypeScript 会 使 用 any 类 型 
RAR o 这 对 代码 转换 来 讲 是 不 错 ， 但 是 使 用 any 意味 着 失去 了 类 型 安全 保障 ， 并 
且 你 得 不 到 工具 的 支持 。 你 可 以 使 用 normplicitAny 选项 ， 让 TypeScript 标 记 出 
发 生 这 种 情况 的 地 方 ， 并 给 出 一 个 错误 。 


严格 的 null 4 undefined 检查 


默认 地 ，TypeScript 把 null 和 undefined 当做 属于 任何 类 型 。 这 就 是 说 ， 上 声明 
A number 类 型 的 值 可 以 为 null 和 undefined ° 因为 在 JavaScript 和 
TypeScript 里 ， null 和 undefined 经 常会 导致 BUG 的 产生 ， 所 以 TypeScript 色 
含 了 strictNullChecks 选项 来 帮助 我 们 减少 对 这 种 情况 的 担忧 。 


当局 用 了 strictNullChecks ， null 和 undefined 获得 了 它们 自己 各 自 的 类 
型 null 和 undefined ° 当 任 何 值 可 能 为 null ， 你 可 以 使 用 联合 类 型 。 比 
如 ， 某 值 可 能 为 number 或 null ， 你 可 以 声明 它 的 类 型 为 number | null 。 


假设 有 一 个 值 TypeScript 认 为 可 以 为 null X undefined ， 但 是 你 更 清楚 它 的 类 
型 ， 你 可 以 使 用 ! 后 级 。 


declare var foo: string[] | null; 
foo.length; // error - 'foo' is possibly 'null' 


foo!.length; // okay - 'foo!' just has type 'string[]' 


要 当心 ， 当 你 使 用 strictNullChecks ， 你 的 依赖 也 需要 相应 地 局 
用 strictNullChecks ° 


this ZAZA any 


当 你 在 类 的 外 部 使 用 this 关键 字 时 ， 它 会 默认 获得 any RA 9 比如， 假设 有 一 
个 Point 类 ， 并 且 我 们 要 添加 一 个 函数 做 为 它 的 方法 : 


class Point { 
constructor (public x, public y) {} 
getDistance(p: Point) { 
let dx = p.x - this.x; 
let dy = p.y - this.y; 
return Math.sgrt(dx ** 2 +t dy ** 2); 


} 
gu 


// Reopen the interface. 
interface Point 1 
distanceFromOrigin(point: Point): number; 


j 
Point.prototype.distanceFromOrigin = function(point: Point) { 
return this.getDistance(( x: 0, y: 0)); 


这 就 产生 了 我 们 上 面 提 到 的 错误 - 如 果 我 们 错误 地 拼写 了 getDistance 并 不 会 得 
到 一 个 错误 。 正 因 此 ，TypeScript 有 noImplicitThis 选项 。 当 设置 了 它 ， 
TypeScript 会 产生 一 个 错误 当 没 有 明确 指定 类 型 (或 通过 类 型 推断 ) 的 this 被 使 
用 时 。 解决 的 方法 是 在 接口 或 函数 上 使 用 指定 了 类 型 的 this 参数 : 


Point.prototype.distanceFromOrigin = function(this: Point, point 
7 POPNE) af 
return this.getDistance({ x: 0, y: 0}); 
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为 了 让 程序 有 价值 ， 我 们 需要 能 够 处 理 最 简单 的 数据 单元 : 数字 ， 字 符 串 ， 结 构 
体 ， 布 尔 值 等 。 TypeScript 支 持 与 JavaScript 几 乎 相同 的 数据 类 型 ， 此 外 还 提供 了 
实用 的 枚 举 类 型 方便 我 们 使 用 。 


布尔 值 


最 基本 的 数据 类 型 就 是 简单 的 true/false 值 ， 在 JavaScript 和 TypeScript 里 叫 
做 boolean (其 它 语言 中 也 一 样 ) 。 


let isDone: boolean = false; 


数字 


和 JavaScript 一 样 ，TypeScript 里 的 所 有 数字 都 是 浮 点 数 。 这些 浮 点 数 的 类 型 
是 number ° 除了 支持 十 进 制 和 十 六 进 制 字面 量 ，TypeScript 还 支持 ECMAScript 
2015 中 引入 的 二 进 制 和 八进制 字面 量 。 


let decLiteral: number 6 

let hexLiteral: number = Oxf00d; 
let binaryLiteral: number = 0b1010; 
let octalLiteral: number = 00744; 


字符 串 


JavaScript 程 序 的 另 一 项 基本 操作 是 处 理 网 页 或 服务 器 端的 文本 数据 。 像 其 它 语言 
里 一 样 ， 我 们 使 用 string 表示 文本 数据 类 型 。 和 JavaScript 一 样 ， 可 以 使 用 双 引 
*(") 或 单 引 号 ( ' ) Am YA P 


let name: string = "bob"; 
name = "smith"; 


你 还 可 以 使 用 模版 字符 囊 ， 它 可 以 定义 多 行文 本 和 内 吝 表 达 式 。 这 种 字符 囊 是 被 反 
引号 包围 ( > ) ， 并 且 以 ${ expr } 这 种 形式 秦 入 表达 式 


let name: string = 'Gene'; 
let age: number = 37; 
let sentence: string = "Hello, my name is ${ name }. 


I'll be ${ age + 1 } years old next month. '; 


这 与 下 面 定义 sentence 的 方式 效果 相同 : 


let sentence: string = "Hello, my name is " + name + ".\n\n" + 
"I'll be " + (age + 1) + " years old next month."; 


数组 


TypeScript 像 JavaScript 一 样 可 以 操作 数组 元 素 。 有 两 种 方式 可 以 定义 数组 。 第 一 
种 ， 可 以 在 元 素 类 型 后 面 接 上 [] ， 表 示 由 此 类 型 元 素 组 成 的 一 个 数组 : 


let list: number[] = [1, 2, 3]; 
第 二 种 方式 是 使 用 数组 泛 型 ， Array< 元 素 类 型 > 


let list: Array<number> = [1, 2, 3]; 


元 组 Tuple 


元 组 类 型 允许 表示 一 个 已 知 元 素数 量 和 类 型 的 数组 ， 各 元 素 的 类 型 不 必 相 同 。 He 
如 ， 你 可 以 定义 一 对 值 分 别 为 string 和 number 类 型 的 元 组 。 


// Declare a tuple type 

let x: [string, number]; 

// Initialize it 

x = [*'hello', 10]; 7/7 OK 

// Initialize it incorrectly 
= (10, *hello® |; -77 Error 


当 访问 一 个 已 知 索 引 的 元 素 ， 会 得 到 正确 的 类 型 : 


console.log(x[0].substr(1)); // OK 
console.log(x[1].substr(1)); // Error, 'number' does not have 


S 
ubstr' 


当 访 问 一 个 越界 的 元 素 ， 会 使 用 联合 类 型 替代 : 
x[3] = 'world'; // 0K， 字 符 串 可 以 赋值 给 (string | number) X! 


console.log(x[5].toString()); // OK, 'string' 和 'number' 都 有 to 
String 


x[6] = true; // Error, /7p*(string | number) X78 


联合 类 型 是 高 级 主题 ， 我 们 会 在 以 后 的 章节 里 讨论 它 。 


enum 类 型 是 对 JavaScript 标 准 数据 类 型 的 一 个 补充 。 像 C# 等 其 它 语 言 一 样 ， 使 
用 枚 举 类 型 可 以 为 一 组 数值 赋予 友好 的 名 字 。 


enum Color {Red, Green, Blue} 
let c: Color = Color.Green; 


默认 情况 下 ， 从 0 开始 为 元 素 编号 。 你 也 可 以 手动 的 指定 成 员 的 数值 。 例 如 ， 我 
们 将 上 面 的 例子 改 成 从 1 开始 编号 : 


enum Color {Red = 1, Green, Blue} 
let c: Color = Color.Green; 


或 者 ， 全 部 都 采用 手动 赋值 : 


enum Color {Red = 1, Green = 2, Blue = 4} 
let c: Color = Color.Green; 


枚 举 类 型 提供 的 一 个 便利 是 你 可 以 由 枚 举 的 值得 到 它 的 名 字 。 例如 ， 我 们 知道 数值 
为 2， 但 是 不 确定 它 映射 到 Color 里 的 哪个 名 字 ， 我 们 可 以 查找 相应 的 名 字 : 


enum Color {Red = 1, Green, Blue} 
let colorName: string = Color[2]; 


alert(colorName); // 显示 'Green' 因 为 上 面 代码 里 它 


任意 值 


有 时 候 ， 我 们 会 想 要 为 那些 在 编程 阶段 还 不 清楚 类 型 的 变量 指定 一 个 类 型 。 这 些 值 
可 能 来 自 于 动态 的 内 容 ， 比 如 来 自用 户 输入 或 第 三 方 代码 库 。 这 种 情况 下 ， 我 们 不 
希望 类 型 检查 器 对 这 些 值 进行 检查 而 是 直接 让 它们 通过 编译 阶段 的 检查 。 那么 我 们 
可 以 使 用 any 类 型 来 标记 这 些 变量 : 


let notSure: any = 4; 
notSure = "maybe a string instead"; 
notSure = false; // okay, definitely a boolean 


在 对 现 有 代码 进行 改写 的 时 候 ， any 类 型 是 十 分 有 用 的 ， 它 允许 你 在 编译 时 可 选 
择 地 包含 或 移 除 类 型 检查 。 你 可 能 认为 0bject 有 相似 的 作用 ， 就 像 它 在 其 它 语 
言 中 那样 。 但 是 Object 类 型 的 变量 只 是 允许 你 给 它 赋 任 意 值 - 但 是 却 不 能 够 在 
它 上 面 调用 任意 的 方法 ， 即 便 它 真 的 有 这 些 方法 : 


let notSure: any = 4; 

notSure.ifItExists(); // okay, ifItExists might exist at runtime 
notSure.toFixed(); // okay, toFixed exists (but the compiler doe 
sn't check) 


let prettySure: Object = 4; 


prettySure.toFixed(); // Error: Property 'toFixed' doesn't exist 
on type 'Object'. 


当 你 只 知道 一 部 分 数据 的 类 型 时 ， any 类 型 也 是 有 用 的 。 比如 ， 你 有 一 个 数组 ， 
它 包 含 了 不 同 的 类 型 的 数据 : 


let list: any[] = [1, true, "free"]; 


list[1] = 100; 


某 种 程度 上 来 说 ， void 类 型 像 是 与 any 类 型 相反 ， 它 表示 没有 任何 类 型 。 当 一 
个 函数 没有 返回 值 时 ， 你 通常 会 见 到 其 返回 值 类 型 是 void 


function warnUser(): void { 


alert("This is my warning message"); 


声明 一 个 void 类 型 的 变量 没有 什么 大 用 ， 因 为 你 只 能 为 它 赋 
P undefined 和 null 


let unusable: void = undefined; 


Null 和 Undefined 


TypeScript 里 ， undefined 和 null 两 者 各 自 有 自己 的 类 型 分 别 叫 
做 undefined 和 null 。 和 void 相似 ， 它 们 的 本 身 的 类 型 用 处 不 是 很 大 : 


// Not much else we can assign to these variables! 
let u: undefined = undefined; 
let n: null = null; 


默认 情况 下 null 和 undefined 是 所 有 类 型 的 子 类 型 。 就 是 说 你 可 以 
把 null 和 undefined 赋值 给 number 类 型 的 变量 。 


然而 ， 当 你 指定 了 --strictNullChecks 标记 ， null 和 undefined 只 能 赋值 
给 void 和 它们 各 自 。 这 能 避免 很 多 常见 的 问题 。 也 许 在 某 处 你 想 传 入 一 

个 string 或 null 或 undefined ， 你 可 以 使 用 联合 类 型 string | null | 
undefined 。 再 次 说 明 ， 稍 后 我 们 会 介绍 联合 类 型 。 


注意 : 我 们 鼓励 尽 可 能 地 使 用 --strictNullCchecks ， 但 在 本 手册 里 我 们 假 


设 这 个 标记 是 关闭 的 。 


Never 


never 类 型 表示 的 是 那些 永 不 存在 的 值 的 类 型 。 例 如 ， never 类 型 是 那些 总 是 
会 抛 出 异常 或 根本 就 不 会 有 返回 值 的 函数 表达 式 或 箭头 函数 表达 式 的 返回 值 类 型 ; 
变量 也 可 能 是 never 类 型 ， 当 它们 被 永 不 为 凌 的 类 型 保护 所 约束 时 。 


never 类 型 是 任何 类 型 的 子 类 型 ， 也 可 以 赋值 给 任何 类 型 ; 然而 ， 没 有 类 型 
是 never 的 子 类 型 或 可 以 赋值 给 never 类 型 (除了 never 本 身 之 外 ) © Bp 
使 any 也 不 可 以 赋值 给 never ° 


下 面 是 一 些 返 回 never 类 型 的 函数 : 


// 返回 never 的 函数 必须 存在 无 法 达到 的 终点 
function error(message: string): never { 
throw new Error(message); 


// 推断 的 返回 值 类 型 为 never 
function fail() { 
return error("Something failed"); 


// 返回 never 的 函数 必须 存在 无 法 达到 的 终点 
function infiniteLoop(): never f 
while (true) { 


} 


Object 


object 表示 非 原始 类 型 ， 也 就 是 
除 number * string * boolean ， symbol * null X undefined 之 外 的 
类 型 。 


使 用 object 类 型 ， 就 可 以 更 好 的 表示 像 Object.create 这 样 的 APl。 例如 : 
declare function create(o: object | null): void; 


create({ prop: 0 }); // OK 
create(null); // OK 


create(42); // Error 
create("string"); // Error 
create(false); // Error 
create(undefined); // Error 


xm 


& 
wh 


有 时 候 你 会 遇 到 这 样 的 情况 ， 你 会 比 TypeScript 更 了 解 某 个 值 的 详细 信息 。 通常 
会 发 生 在 你 清楚 地 知道 一 个 实体 具有 比 它 现 有 类 型 更 确切 的 类 型 。 


[x 


通过 类 型 断言 这 种 方式 可 以 告诉 编译 器 ，"“ 相 信 我 ， 我 知道 自己 在 干什么 ”。 类 型 断 
言 好 比 其 它 语言 里 的 类 型 转换 ， 但 是 不 进行 特殊 的 数据 检查 和 解构 。 它 没有 运行 时 


的 影响 ， 只 是 在 编译 阶段 起 作用 。 TypeScript 会 假设 你 ， 程 序 员 ， 已 经 进行 了 必须 
的 检查 。 


类 型 断言 有 两 种 形式 。 其 一 是 “ 尖 括 号 "语法 : 
let someValue: any = "this is a string"; 


let strLength: number = (<string>someValue) .length; 


另 一 个 为 as 语法 : 
let someValue: any = "this is a string"; 


let strLength: number = (someValue as string).length; 


两 种 形式 是 等 价 的 。 至 于 使 用 哪个 大 多 数 情 况 下 是 赁 个 人 喜好 ; 然而 ， 当 你 在 
TypeScript 里 使 用 JSX 时 ， 只 有 as 语法 断言 是 被 允许 的 。 


KT let 


你 可 能 已 经 注意 到 了 ， 我 们 使 用 let 关键 字 来 代替 大 家 所 熟悉 的 JavaScript 关 键 
字 var 。 let 关键 字 是 JavaScript 的 一 个 新 概念 ，TypeScript 实 现 了 它 。 我 们 会 
在 以 后 详细 介绍 它 ， 很 多 常见 的 问题 都 可 以 通过 使 用 let 来 解决 ， 所 以 尽 可 能 地 
使 用 let KAA var Ge 


23 量 声明 


let 和 const 是 JavaScript 里 相对 较 新 的 变量 声明 方式 。 像 我 们 之 前 提 到 过 
的 ， let 在 很 多 方面 与 var 是 相似 的 ， 但 是 可 以 帮助 大 家 避免 在 JavaScript 里 常 


见 一 些 问 题 。 const 是 对 let 的 一 个 增强 ， 它 能 阻止 对 一 个 变量 再 次 赋值 。 


因为 TypeScript 是 JavaScript 的 超 集 ， 所 以 它 本 身 就 支持 let 和 const 。 下 面 我 
们 会 详细 说 明 这 些 新 的 声明 方式 以 及 为 什么 推荐 使 用 它们 来 代替 var 。 


如 果 你 之 前 使 用 JavaScript 时 没有 特别 在 意 ， 那 么 ee o de 
你 已 经 对 var 声明 的 怪异 之 处 了 如 指 掌 ， 那 么 你 可 以 轻松 地 略 过 
= 
var 声明 
一 直 以 来 我 们 都 是 通过 var KF x LJavaScript® € ° 
var a = 10; 


大 家 都 能 理解 ， 这 里 定义 了 一 个 名 为 a 4 10 的 变量 。 


我 们 也 可 以 在 函数 内 部 定义 变量 


function f() { 
var message = "Hello, world!"; 


return message; 


并 且 我 们 也 可 以 在 其 它 函 数 内 部 访问 相同 的 变量 。 


FURnCELON O 
var a = 10; 
return function g() { 
var b-a-* 1; 
return b; 


var g - f(); 
GO); 7/ returns 11; 


上 面 的 例子 里 ，g 可 以 获取 到 f BRECVLH a 变量 。 每 当 g 被 调用 时 ， 它 
都 可 以 访问 到 f 里 的 a 变量 。 即 使 当 g 在 f 已 经 执行 完 后 才 被 调用 ， 它 仍然 
可 以 访问 及 修改 a 。 


function f() { 
var a= 1; 


de 0 
var b = g(); 
a= 3: 
return b; 


function go) f 
return a; 


f(); // returns 2 


作用 域 规则 


对 于 熟悉 其 它 语言 的 人 来 说 ， var 声明 有 些 奇 怪 的 作用 域 规则 。 看 下 面 的 例子 : 


function f(shouldInitialize: boolean) { 
if (shouldInitialize) { 
var x = 10; 


return x; 


f(true); // returns '10' 
f(false); // returns 'undefined' 


有 些 读者 可 能 要 多 看 几 遍 这 个 例子 。 RE x 是 定义 在 if a ae. ， 但 是 我 们 却 
可 以 在 语句 的 外 面 访问 它 。 这 是 因为 var 声明 可 以 在 包含 它 的 函数 ， 模 块 ， 命 名 
空间 或 全 局 作用 域内 部 任何 位 置 ea MAE ai 
对 此 没有 什么 影响 。 有 些 人 称 此 为 var 作用 域 或 函 AT Be - KHIR RAIL E] BH 
数 作用 域 。 


Ka 
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这 些 作 用 域 规则 可 能 会 引发 一 些 错误 。 其 中 之 一 就 是 ， 多 次 声明 同一 个 变 
报错 : 


function sumMatrix(matrix: number[][]) { 
var sum = 0; 
for (var i = 0; i < matrix.length; i++) ( 
var currentRow = matrix[i]; 
for (var i = 0; i < currentRow.length; i++) ( 
sum += currentRow[i]; 


return sum; 


这 里 很 容易 看 出 一 些 问 题 ， 里 层 的 for 循环 会 ainsad. Mouk Ep 
相同 的 元 数 作 用 域内 的 变量 。 有 经 验 的 开发 者 们 很 清楚 ， 这 些 问 题 可 能 在 代码 审查 
时 漏 掉 ， 引 发 无 穷 的 麻烦 。 


捕获 变量 怪 开 之 处 


快速 的 猜 一 下 下 面 的 代码 会 返回 什么 : 


for (var d= 0, a= 10) d+) 1 
setTimeout(function() { console.log(i); }, 100 * i); 


介绍 一 下 ， setTimeout 会 在 若干 毫秒 的 延 时 后 执行 一 个 函数 (等待 其 它 代码 执 
) 


好 吧 ， 看 一 下 结果 : 


10 
10 
10 
10 
10 
10 
10 
10 
10 
10 


Ac 大 多 数 人 期 望 输出 结果 是 这 样 : 


Oo ON OO RA 0 I|! Oo 


还 记得 我 们 上 面 提 到 的 捕获 变量 吗 ? 我 们 传 给 setTimeout 的 每 一 个 函数 表达 式 
实际 上 都 引用 了 相同 作用 域 里 的 同一 个 i 。 


让 我 们 花 点 时 间 思 考 一 下 这 是 为 什么 。 setTimeout 在 若干 毫秒 后 执行 一 个 遂 
数 ， 并 且 是 在 for 循环 结束 后 。 for MAAR? i HMA 10 9 BP[VA h 
数 被 调用 的 时 候 ， 它 会 打印 出 10 |! 


一 个 通常 的 解决 方法 是 使 用 立即 执行 的 函数 表达 式 (IFE) 来 捕获 每 次 迭代 
时 i 的 值 : 


for (var 1 Op < 10 Tt 
// capture the current state of 'i' 
// by invoking a function with its current value 
(function(i) { 
setTimeout(function() { console.log(i); }, 100 * i); 


H(i); 


这 种 奇怪 的 形式 我 们 已 经 司空 见 惯 了 。 参数 i SRA for 循环 里 的 i ， 但 是 因 
为 我 们 起 了 同样 的 名 字 ， 所 以 我 们 不 用 怎么 改 for 循环 体 里 的 代码 。 


let 声明 


现在 你 已 经 知道 了 var 存在 一 些 问 题 ， 这 恰好 说 明了 为 什么 用 let i6] d 5 8] 0E 
量 。 除 了 名 字 不 同 外 ， let 与 var 的 写法 一 致 。 


let hello = "Hello!"; 
主要 的 区 别 不 在 语法 上 ， 而 是 语义 ， 我 们 接 下 来 会 深入 研究 。 


块 作用 域 


当 用 let 声明 一 个 变量 ， 它 使 用 的 是 词法 作用 域 或 块 作用 域 。 不 同 于 使 
用 var 声明 的 变量 那样 可 以 在 包含 它们 的 函数 外 访问 ， 块 作用 域 变 量 在 包含 它们 
的 块 或 for 循环 之 外 是 不 能 访问 的 。 


function f(input: boolean) { 
let a = 100; 


if (input) { 
// Still okay to reference 
let b =a + 1; 
return b; 


1 


a I 


// Error: 'b' doesn't exist here 
return b; 


这 里 我 们 定义 了 2 个 变量 af b 。 a 的 作用 域 是 f HAAA?’ A b 的 作用 域 
是 if 语句 块 里 。 


在 catch 语句 里 声明 的 变量 也 有 具有 同样 的 作用 域 规则 。 


try T 
throw "oh no!"; 
} 
catch (e) { 
console.log("Oh well."); 
} 


// Error: 'e' doesn't exist here 
console.log(e); 


拥有 块 级 作用 域 的 变量 的 另 一 个 特点 是 ， 它 们 不 能 在 被 声明 之 前 读 或 写 。 虽然 这 些 
变量 始终 “存在 "于 它们 的 作用 域 里 ， 但 在 直到 声明 它 的 代码 之 前 的 区 域 都 属于 暂时 
性 死 区 。 它 只 是 用 来 说 明 我 们 不 能 在 let 语句 之 前 访问 它们 ， 幸 运 的 是 
TypeScript 可 以 告诉 我 们 这 些 信 息 。 


att; // illegal to use 'a' before it's declared; 
let a; 


注意 一 点 ， 我 们 仍然 可 以 在 一 个 拥有 块 作用 域 变 量 被 声明 前 获取 它 。 只 是 我 们 不 能 
在 变量 声明 前 去 调用 那个 函数 。 如 果 生 成 代码 目标 为 ES2015， 现 代 的 运行 时 会 抛 
出 一 个 错误 ; 然而 ， 现 今 TypeScript 是 不 会 报错 的 。 


function foo() { 
// okay to capture 'a' 


return a; 
} 
// 不 能 在 'a' 被 声明 前 调用 'foo' 
// 运行 时 应 该 » Kun 
foo(); 
let a; 


关于 暂时 性 死 区 的 更 多 信息 ， 查 看 这 里 Mozilla Developer Network 
重 定义 及 屏蔽 
我 们 提 过 使 用 var 声明 时 ， 它 不 在 乎 你 声明 多 少 次 ; 你 只 会 得 到 1 个 。 


function: f(x) 1 
var X; 
var X; 


if (true) ( 
var X; 


在 上 面 的 例子 里 ， 所 有 x 的 声明 实际 上 都 引用 一 个 相同 的 x ， Comal 


的 代码 。 这 经 常会 成 为 bug 的 来 源 。 好 的 是 ， let 声明 就 不 会 这 么 宽松 了 。 
let x = 10; 
let x = 20; // 错误 ， 不 能 在 1 个 作用 域 里 多 次 声明 `X、 


并 不 是 要 求 两 个 均 是 块 级 作用 域 的 声明 TypeScript 才 会 给 出 一 个 错误 的 警告 。 


Function o ox) 
let x = 100; // error: interferes with parameter declaration 


function g() { 
let x = 100; 
var x = 100; // error: can't have both declarations of 


1 I 


X 


并 不 是 说 块 级 作用 域 变 量 不 能 用 函数 作用 域 变量 来 声明 。 而 是 块 级 作用 域 变 量 需要 
在 明显 不 同 的 块 里 声明 o 


function focondition, x) E 
if (condition) { 
let x = 100; 
return x; 


return x; 


f(false, ©); // returns 0 
f(true, 0); // returns 100 


4 — ^k ATEnRUESIX— A31 894129 BRR 。 它 是 一 把 双 刃 剑 ， 它 可 能 会 
不 小 心地 引入 新 问题 ， 同 时 也 可 能 会 解决 一 些 错 误 。 例如 ， 人 假设 我 们 现在 
用 let 重 写 之 前 的 sumMatrix 2 © 


function sumMatrix(matrix: number[][]) { 
let sum = 0; 
for (let i = 0; i « matrix.length; i++) ( 
var currentRow = matrix[i]; 
for (let i = 0; i < currentRow.length; i++) { 
sum += currentRow[i]; 


return sum; 


这 个 版 本 的 循环 能 得 到 正确 的 结果 ， 因 为 内 层 循环 的 i 可 以 屏蔽 掉 外 层 循环 
ay i œ 


通常 来 讲 应 该 避免 使 用 屏蔽 ， 因 为 我 们 需要 写 出 清晰 的 代码 。 同时 也 有 些 场景 适合 
用 它 ， 你 需要 好 好 打算 一 下 。 


块 级 作用 域 变量 的 获取 


在 我 们 最 初 谈 及 获取 用 var 声明 的 变量 时 ， 我 们 简略 地 探 完了 一 下 在 获取 到 了 变 
量 之 后 它 的 行为 是 怎样 的 。 直观 地 讲 ， 每 次 进入 一 个 作用 域 时 ， 它 创建 了 一 个 变量 
的 环境 。 就 算 作用 域内 代码 已 经 执行 完毕 ， 这 个 环境 与 其 捕获 的 变量 依然 存在 。 


function theCityThatAlwaysSleeps() { 
let getCity; 


if (true) { 
let city = "Seattle"; 
getCity = function() { 
return city; 


return getCity(); 


因为 我 们 已 经 在 city 的 环境 里 获取 到 了 city ， 所 以 就 算 if 语句 执行 结束 后 
我 们 仍然 可 以 访问 它 。 


回想 一 下 前 面 setTimeout 的 例子 ， 我 们 最 后 需要 使 用 立即 执行 的 函数 表达 式 来 
获取 每 次 for 循环 迭代 里 的 状态 。 实际 上 ， 我 们 做 的 是 为 获取 到 的 变量 创建 了 一 
个 新 的 变量 环境 。 这 样 做 挺 痛苦 的 ， 但 是 幸运 的 是 ， 你 不 必 在 TypeScript 里 这 样 做 
T3 

33 let 声明 出 现在 循环 体 里 时 拥有 完全 不 同 的 行为 。 不仅 是 在 循环 里 引入 了 一 个 
新 的 变量 环境 ， 而 是 针对 每 次 迭代 都 会 创建 这 样 一 个 新 作用 域 。 这 就 是 我 们 在 使 用 
立即 执行 的 函数 表达 式 时 做 的 事 ， 所 以 在 setTimeout 例子 里 我 们 仅 使 用 let F 
明 就 可 以 了 。 


for (ret 1 — 0; 3 $ 10 = at) f 
setTimeout(function() [console.log(i); }, 100 * i); 


会 输出 与 预料 一 致 的 结果 : 


o Oo - OO 25 0 I|! Oo 


ac 
const 声明 
const 声明 是 声明 变量 的 另 一 种 方式 。 


const numLivesForCat = 9; 


它们 与 let 声明 相似 ， 但 是 就 像 它 的 名 字 所 表达 的 ， 它 们 被 赋值 后 不 能 再 改变 。 
换 名 话说， 它们 拥有 与 let 相同 的 作用 域 规则 ， 但 是 不 能 对 它们 重新 赋值 。 


这 很 好 理解 ， 它 们 引用 的 值 是 不 可 变 的 。 


const numLivesForCat = 9; 
const kitty = { 

name: "Aurora", 

numLives: numLivesForCat, 


B 
Wii Ea CIS 
kitty - ( 
name: "Danielle", 
numLives: numLivesForCat 
e 


// all "okay" 
kitty.name - "Rory"; 
kitty.name - "Kitty"; 
kitty.name - "Cat"; 


kitty.numLives--; 


除非 你 使 用 特殊 的 方法 去 避免 ， 实际 上 const 变量 的 内 部 状态 是 可 修改 的 。 幸运 
的 是 ，TypeScript 允 许 你 将 对 象 的 成 员 设置 成 只 读 的 。 接口 一 章 有 详细 说 明 。 


let vs. const 


现在 我 们 有 两 种 作用 域 相 似 的 声明 方式 ， 我 们 自然 会 问 到 底 应 该 使 用 哪个 。 与 大 多 
数 泛泛 的 问题 一 样 ， 答 案 是 : 依 情况 而 定 。 

使 用 最 小 特权 原则 ， 所 有 变量 除了 你 计划 去 修改 的 都 应 该 使 用 const 。 基本 原则 
就 是 如 果 一 个 变量 不 需要 对 它 写 入 ， 那 么 其 它 使 用 这 些 代码 的 人 也 不 能 够 写 入 它 
们 ， 并 且 要 思考 为 什么 会 需要 对 这 些 变量 重新 赋值 。 使 用 const 也 可 以 让 我 们 更 
容易 的 推测 数据 的 流动 。 


跟 据 你 的 自己 判断 ， 如 果 合 适 的 话 ， 与 团队 成 员 商 议 一 下 。 


这 个 手册 大 部 分 地 方 都 使 用 了 let 声明 。 


解构 


Another TypeScript 已 经 可 以 解析 其 它 ECMAScript 2015 特性 了 。 完整 列表 请 参见 
the article on the Mozilla Developer Network。 本 章 ， 我 们 将 给 出 一 个 简短 的 概 
ro 


解构 数组 
最 简单 的 解构 英 过 于 数组 的 解构 赋值 了 : 


let input = [1, 2]; 

let [first, second] = input; 
console.log(first); // outputs 1 
console.log(second); // outputs 2 


这 创建 了 2 个 命名 变量 first 和 second » 相当 于 使 用 了 索引 ， 但 更 为 方便 : 


first = input[0]; 
second = input[i]; 


解构 作用 于 已 声明 的 变量 会 更 好 : 


// swap variables 
[first, second] = [second, first]; 


作用 于 函数 参数 : 


function f([first, second]: [number, number]) { 
console.log(first); 
console.log(second); 


} 
f(input); 


你 可 以 在 数组 里 使 用 ,,， 语法 创建 剩余 变量 : 


let [farst, ...rest] = [1, 2, 3, 4]; 
console.log(first); // outputs 1 
console.log(rest); // outputs [ 2, 3, 4 ] 


4R> ht X JavaScript, 你 可 以 忽略 你 不 关心 的 尾随 元 素 : 


let [fsrst]| = [4, 2, 3s, 4]; 
console.log(first); // outputs 1 


let [, second, , fourth] = [1, 2, 3, 4]; 


对 象 解构 


你 也 可 以 解构 对 象 : 
let o = { 
ay OO 
D: ls 
c: "bar" 
J; 


通过 o.a and o.b 创建 了 a 和 b 。 注意 ， 如 果 你 不 需要 c 你 可 以 忽 
它 
就 像 数组 解构 ， 你 可 以 用 没有 声明 的 赋值 : 

({ a, b) = (a: "baz", b: 101 3); 


注意 ， 我 们 需要 用 括号 将 它 括 起 来 ， 因 为 Javascript 通 常会 将 以 ( 起 始 的 语句 解 
析 为 一 个 块 。 


你 可 以 在 对 象 里 使 用 ..， 语 法 创建 剩余 变量 : 


let { a, ...passthrough } = 
let total = passthrough.b + passthrough.c.length; 


属性 重 命名 


你 也 可 以 给 属性 以 不 同 的 名 字 : 


let { a: newName1, b: newName2 } = 


这 里 的 语法 开始 变 得 混乱 。 你 可 以 将 a: newNamei 读 做 " a 作为 
newName1 "° 方向 是 从 左 到 右 ， 好 像 你 写成 了 以 下 样子 : 


let newName1 = o.a; 
let newName2 = o.b; 


令 人 困惑 的 是 ， 这 里 的 冒号 不 是 指示 类 型 的 。 如 果 你 想 指定 它 的 类 型 ， 仍 然 需要 
在 其 后 写 上 完整 的 模式 。 


let fa, b}: (a: string, b: number} = 


默认 值 
默认 值 可 以 让 你 在 属性 为 undefined 时 使 用 缺 省 值 : 


function keepWholeObject(wholeObject: { a: string, b?: number }) 
{ 


let { a, b = 1001 } = wholeObject; 
E eee 


现在 ， 即 使 b A undefined >  keepwholeObject 函数 的 变量 wholeObject 
的 属性 a 和 b 都 会 有 值 。 


IER 


t1 4,86 H Bao 看 以 下 简单 的 情况 : 


type C = { a: string, b?: number } 
unctione ag a pe ©). vold i 
AR 


但 是 ， 通 常情 况 下 更 多 的 是 指定 软 认 值 ， 解 构 默认 值 有 些 环 手 。 首先 ， 你 需要 在 默 
认 值 之 前 设置 其 格式 。 


function f({ a, b}=4{a: "", b: © }): void { 
EE 


} 
f(); // ok, default to { a: "", b: 0 } 


上 面 的 代码 是 一 个 类 型 推断 的 例子 ， 将 在 本 手册 后 文 介绍 。 


其 次 ， 你 需要 知道 在 解构 属性 上 给 予 一 个 默认 或 可 选 的 属性 用 来 替换 主 初始 化 列 
Reo 要 知道 C 的 定义 有 一 个 b 可 选 属性 


function f({ a, b=0 } = { a: "" }): void { 
1S arene 


} 
f({ a: "yes" }); // ok, default b = 0 


f(); // ok, default to (a: ""}, which then defaults b = 0 
f((3); // error, 'a' is required if you supply an argument 


要 小 心 使 用 解构 。 MAT en lp 9D VUE > SCIL Ze ica] 3e 09] EAS GG AL EU 
解 的 。 DA HERE i AAIR RHEAN RARE EY € 4 E > ERA 
值 和 类 型 注解 ， 也 是 令 人 难以 理解 的 。 解构 表达 式 要 尽量 保持 小 而 简单 。 你 自己 
也 可 以 直接 使 用 解构 将 会 生成 的 赋值 表达 式 。 


展开 


展开 操作 符 正 与 解构 相反 。 它 允 许 你 将 一 个 数组 展开 为 另 一 个 数组 ， 或 将 一 个 对 象 
展开 为 另 一 个 对 象 。 例如 : 


let first = [1, 2]; 
let second = [3, 4]; 
let bothPlus = [0, ...first, ...second, 5]; 


这 会 令 bothPlus “444 [0, 1, 2, 3, 4, 5] » 展开 操作 创建 
了 first 和 second 的 一 份 浅 拷贝 。 它 们 不 会 被 展开 操作 所 改变 。 


你 还 可 以 展开 对 象 : 


let defaults = { food: "Spicy", price: "$$", ambiance: "noisy" } 


let search = { ...defaults, food: "rich" }; 


search 的 值 为 { food: "rich", price: "$$", ambiance: "noisy" } ° 对 
象 的 展开 比 数组 的 展开 要 复杂 的 多 。 像 数组 展开 一 样 ， 它 是 从 左 至 右 进 行 处 理 ， 但 
结果 仍 为 对 象 。 这 就 意味 着 出 现在 展开 对 象 后 面 的 属性 会 覆盖 前 面 的 属性 。 A 

此 ， 如 果 我 们 修改 上 面 的 例子 ， 在 结尾 处 进行 展开 的 话 : 


let defaults = { food: "Spicy", price: "$$", ambiance: "noisy" } 


let search = { food: "rich", ...defaults }; 


那么 ， defaults 里 的 food 属性 会 重 写 food: "rich" ， 在 这 里 这 并 不 是 我 们 
想 要 的 结果 。 


对 象 展开 还 有 其 它 一 些 意 想 不 到 的 限制 。 HA? CRASHR 自身 的 可 枚 举 属 
性 。 大 体 上 是 说 当 你 展开 一 个 对 象 实例 时 ， 你 会 去 失 其 方法 : 


class C { 


pcm. 
m() { 
} 


} 

let c = new C(); 

let clone = { ...c }; 
clone.p; // ok 
clone.m(); // error! 


其 次 ，TypeScript 编 译 器 不 允许 展开 泛 型 函数 上 的 类 型 参数 。 这 个 特性 会 在 
TypeScript 的 未 来 版 本 中 考虑 实现 。 


TypeScript 的 核心 原则 之 一 是 对 值 所 具有 的 结构 进行 类 型 检查 。 它 有 时 被 称 做 “ 鸭 式 
状 型 法 "或 “结构 性 子 类 型 化 "。 在 TypeScript 里 ， 接 口 的 作用 就 是 为 这 些 类 型 命名 和 
为 你 的 代码 或 第 三 方 代码 定义 契约 。 


接口 初探 
下 面 通过 一 个 简单 示例 来 观察 接口 是 如 何 工作 的 : 


function printLabel(labelledObj: { label: string }) { 
console.log(labelledObj.label); 
} 


let myObj = { size: 10, label: "Size 10 Object" }; 
printLabel(myObj); 


类 型 检查 器 会 查看 printLabel 的 调用 。 printLabel 有 一 个 参数 ， 并 要 求 这 个 
对 象 参数 有 一 个 名 为 label 类 型 为 string 的 属性 。 需要 注意 的 是 ， 我 们 传 入 的 
对 象 参数 实际 上 会 包含 很 多 属性 ， 但 是 ee 的 属性 是 否 存 在 ， 
并 且 其 类 型 是 否 匹 配 。 然而 ， 有些 时 候 TypeScript 却 并 不 会 这 么 宽松 ， 我 们 下 面 会 
稍 做 讲解 。 


下 面 我 们 重 写 上 面 的 例子 ， 这 次 使 用 接口 来 描述 : 必须 包含 一 个 label 属性 且 类 
型 为 string 


interface LabelledValue { 
label: string; 


} 


function printLabel(labelledObj: LabelledValue) ( 
console.log(labelledObj.label); 
} 


let myObj = {size: 10, label: "Size 10 Object"}; 
printLabel(myObj); 


Labelledvalue 接口 就 好 比 一 个 名 字 ， 用 来 描述 上 面 例子 里 的 要 求 。 它 代表 了 有 
一 个 label 属性 且 类 型 为 string 的 对 象 。 需 要 注意 的 是 ， 我 们 在 这 里 并 不 能 像 
在 其 它 语言 里 一 样 ， 说 传 给 printLabel 的 对 象 实现 了 这 个 接口 。 我 们 只 会 去 关 
注 值 的 外 形 。 只 要 传 入 的 对 象 满足 上 面 提 到 的 必要 条 件 ， 那 么 它 就 是 被 允许 的 。 


还 有 一 点 值得 提 的 是 ， 类 型 检查 器 不 会 去 检查 属性 的 顺序 ， 只 要 相应 的 属性 存在 并 
且 类 型 也 是 对 的 就 可 以 。 


可 选 属性 


接口 里 的 属性 不 全 都 是 必需 的 。 有些 是 只 在 某 些 条 件 下 存在 ， 或 者 根本 不 存在 。 
可 选 属性 在 应 用 "option bags” 模 式 时 很 党 用 ， 即 给 函数 传 入 的 参数 对 象 中 只 有 部 分 
属性 赋值 了 。 


下 面 是 应 用 了 "option bags” 的 例子 : 


interface SquareConfig { 
color?: string; 
width?: number; 


function createSquare(config: SquareConfig): {color: string; are 
a: number} { 
let newSquare = {color: "white", area: 100}; 
if (config.color) { 
newSquare.color - config.color; 


j 
if (config.width) ( 
newSquare.area - config.width * config.width; 


j 


return newSquare; 


let mySquare = createSquare({color: "black"}); 


带 有 可 选 属性 的 接口 与 普通 的 接口 定义 差不多 ， 只 是 在 可 选 属性 名 字 定 义 的 后 面 加 
一 个 ? 符号 。 


可 选 属性 的 好 处 之 一 是 可 以 对 可 能 存在 的 属性 进行 预定 义 ， 好 处 之 二 是 可 以 捕获 引 


用 了 不 存在 的 属性 时 的 错误 。 比如 ， 我 们 故意 将 createsquare 里 的 color & 
性 名 拼 错 ， 就 会 得 到 一 个 错误 提示 : 


interface SquareConfig { 
Color? string; 
width?: number; 


function createSquare(config: SquareConfig): { color: string; ar 
ea: number } { 
let newSquare = {color: "white", area: 100}; 
if (config.clor) { 
// Error: Property 'clor' does not exist on type 'SquareConf 


ig' 
newSquare.color = config.clor; 


j 
if (config.width) ( 
newSquare.area - config.width * config.width; 


j 


return newSquare; 


let mySquare = createSquare({color: "black"}); 


一 些 对 象 属 性 只 能 在 对 象 刚 刚 创建 的 时 候 修改 其 值 。 你 可 以 在 属性 名 前 
用 readonly 来 指定 只 读 属 性 : 


interface Point { 
readonly x: number; 
readonly y: number; 


你 可 以 通过 赋值 一 个 对 象 字面 量 来 构造 一 个 Point 9 赋值 后 ， x fe y 再 也 不 能 


被 改变 了 。 


Tet pl: Point =< x: 410 v: 20 17 
Dix = 57 // error! 


TypeScript 具 有 ReadonlyArray«T» 类 型 ， 它 与 Array<T> 相似 ， 只 是 把 所 有 可 
变 方 法 去 掉 了 ， 因 此 可 以 确保 数组 创建 后 再 也 不 能 被 修改 : 


let a: number[] = [1, 2, 3, 4]; 
let ro: ReadonlyArray<number> = a; 
ro[0] = 12; /7 error! 

ro.push(5); // error! 

ro.length = 100; // error! 


a = ro; // error! 


上 面 代码 的 最 后 一 行 ， 可 以 看 到 就 算 把 整个 ReadonlyArray 赋值 到 一 个 普通 数组 
也 是 不 可 以 的 。 但 是 你 可 以 用 类 型 断言 重 写 : 


a = ro as number[]; 


readonly vs const 


wv kk 


最 简单 判断 该 用 readonly 还 是 const 的 方法 是 看 要 把 它 做 为 变量 使 用 还 是 做 为 
一 个 属性 。 做 为 变量 使 用 的 话 用 const ， 若 做 为 属性 则 使 用 readonly » 


额外 的 属性 检查 


我 们 在 第 一 个 例子 里 使 用 了 接口 ，TypeScript 让 我 们 传 入 ( size: number; 
label: string; } 到 仅 期 望 得 到 { label: string; ) 的 函数 里 。 我 们 已 经 学 
过 了 可 选 属性 ， 并 且 知 道 他 们 在 “option bags” 模 式 里 很 有 用 。 


然而 ， 天 扶 地 将 这 两 者 结合 的 话 就 会 像 在 JavaScript 里 那样 搬 起 石头 砸 自己 的 脚 。 
Hite > € createSquare 例子 来 说 : 


interface SquareConfig { 
color?: string; 
width?: number; 


function createSquare(config: SquareConfig): { color: string; ar 
ea: number } { 
y E 


let mySquare = createSquare({ colour: "red", width: 100 }); 


注意 传 入 createSquare 的 参数 拼写 为 colour 而 不 是 color ° #JavaScript 
里 ， 这 会 默默 地 失败 。 


你 可 能 会 争辩 这 个 程序 已 经 正确 地 类 型 化 了 ， 因 为 width 属性 是 兼容 的 ， 不 存 
在 color 属性 ， 而 且 额 外 的 colour 属性 是 无 意义 的 。 


然而 ，TypeScript 会 认为 pesto o 对 象 字 面 量 会 被 特殊 对 待 而 且 会 
经 过 额外 属性 检查 ， 当 将 它们 赋值 给 变量 习 PA 参数 传递 的 时 候 。 如 果 一 个 对 象 字 
面 量 存 在 任何 “目标 类 型 "不 包含 的 属性 时 ， 你 会 得 到 一 个 错误 。 


// error: 'colour' not expected in type 'SquareConfig' 
let mySquare = createSquare(( colour: "red", width: 100 }); 


绕 开 这 些 检查 非常 简单 。 最 简便 的 方法 是 使 用 类 型 断言 : 


let mySquare = createSquare({ width: 100, opacity: 0.5 } as Squa 
reConfig); 


然而 ， 最 佳 的 方式 是 能 够 添加 一 个 字符 串 索 引 签 名 ， 前 提 是 你 能 够 确定 这 个 对 象 可 
能 具有 某 些 做 为 特殊 用 途 使 用 的 额外 属性 。 如 果 SquareConfig 带 有 上 面 定义 的 
类 型 的 color 和 width 属性 ， 并 且 还 会 带 有 任意 数量 的 其 它 属 性 ， 那 么 我 们 可 
以 这 样 定 义 它 


interface SquareConfig { 
color?: string; 
width?: number; 
[propName: string]: any; 


我 们 稍 后 会 讲 到 索引 签名 ， 但 在 这 我 们 要 表示 的 是 SquareConfig 可 以 有 任意 数 
量 的 属性 ， 并 且 只 要 它们 不 是 color fe width ， 那 么 就 无 所 谓 它 们 的 类 型 是 什 
A Oo 


还 有 最 后 一 种 跳 过 这 些 检查 的 方式 ， 这 可 能 会 让 你 感到 惊讶 ， 它 就 是 将 这 个 对 象 赋 
值 给 一 个 另 一 个 变量 : 因为 squareOptions 不 会 经 过 额外 属性 检查 ， 所 以 编译 器 
不 会 报错 。 


let squareOptions = { colour: "red", width: 100 }; 
let mySquare = createSquare(squareOptions); 


要 留意 ， 在 像 上 面 一 样 的 简单 代码 里 ， 你 可 能 不 应 该 去 绕 开 这 些 检查 。 HT AS 
法 和 内 部 状态 的 复杂 对 象 字 面 量 来 讲 ， 你 可 能 需要 使 用 这 些 技巧 ， 但 是 大 部 额外 属 
性 检查 错误 是 真正 的 bug。 就 是 说 你 遇 到 了 额外 类 型 检查 出 的 错误 ， 比 如 “option 
bags”， 你 应 该 去 审查 一 下 你 的 类 型 声明 。 在 这 里 ， 如 果 支 持 传 

入 color 或 colour 属性 到 createSquare ， 你 应 该 修改 SquareConfig 定义 
来 体现 出 这 一 点 。 


E Fe KA 


接口 能 够 描述 JavaScript 中 对 象 拥有 的 各 种 各 样 的 外 形 。 除 了 描述 带 有 属性 的 普通 
对 象 外 ， 接 口 也 可 以 描述 函数 类 型 。 


为 了 使 用 接口 表示 函数 类 型 ， 我 们 需要 给 接口 定义 一 个 调用 签名 。 它 就 像 是 一 个 只 
有 参数 列表 和 返回 和 值 类 型 的 函数 定义 。 参 数列 表 里 的 每 个 参数 都 需要 名 字 和 类 型 。 


interface SearchFunc { 
(source: string, subString: string): boolean; 


这 样 定义 后 oe 它 接口 一 样 使 用 这 个 函数 类 型 的 接口 。 下 例 展 示 了 
如 何 创 建 子 数 类 型 的 变量 ， 并 将 一 个 同类 型 的 函数 赋值 给 这 个 变量 。 


let mySearch: SearchFunc; 

mySearch = function(source: string, subString: string) { 
let result - source.search(subString); 
return result » -1; 


对 于 函数 类 型 的 类 型 检查 来 说 ， 函 数 的 参数 名 不 需要 与 接口 里 定义 的 名 字 相 匹配 。 
比如 ， 我 们 使 用 下 面 的 代码 重 写 上 面 的 例子 : 


let mySearch: SearchFunc; 

mySearch = function(src: string, sub: string): boolean ( 
let result - src.search(sub); 
return result » -1; 


函数 的 参数 会 逐个 进行 检查 ， 要 求 对 应 位 置 上 的 参数 类 型 是 兼容 的 。 如 果 你 不 想 指 
定 类 型 ，TypeScript 的 类 型 系 , cs 数 直接 赋值 给 

了 SearchFunc 类 型 变量 。 遂 数 的 返回 值 类 型 是 其 返回 值 推断 出 来 的 (此 例 
是 false 和 true ) n: ui. 
们 元 数 的 返回 值 类 型 与 SearchFunc 接口 中 的 定义 不 匹配 。 


let mySearch: SearchFunc; 

mySearch = function(src, sub) { 
let result = src.search(sub); 
return result > -1; 


可 索引 的 类 型 

与 使 用 接口 描述 函数 类 型 差不多 ， 我 们 也 可 以 描述 那些 能 够 < 通过 索引 得 到 "的 类 
型 ， 比 如 a[10] 或 ageMap["daniel"] 。 可 索引 类 型 具有 一 个 索引 签名 ， 它 描 
述 了 对 象 索 引 的 类 型 ， 还 有 相应 的 索引 返回 值 类 型 。 让 我 们 看 一 个 例子 : 


sY 


interface StringArray { 
[index: number]: string; 


let myArray: StringArray; 
myArray = ["Bob", "Fred"]; 


let myStr: string = myArray[0]; 


上 面 例子 里 ， 我 们 定义 了 StringArray 接口 ， 它 具有 索引 签名 。 这 个 索引 签名 表 
示 了 当 用 number 去 索引 StringArray 时 会 得 到 string a 回 值 。 


共有 支持 两 种 索引 签名 : 字符 串 和 数字 。 可 以 同时 使 用 两 种 类 型 的 索引 ， 但 是 数字 
索引 的 返回 值 必 须 是 字符 串 索 引 返 回 值 类 型 的 子 类 型 。 这 是 因为 当 使 

用 number 来 索引 时 ，JavaScript 会 将 它 转换 成 string 然后 再 去 索引 对 象 。 也 

就 是 说 用 100 (一 个 number ) 去 索引 等 同 于 使 用 "100" (一 个 string ) 去 
索引 ， 因 此 两 者 需要 保持 一 致 。 


class Animal { 
name: string; 

} 

class Dog extends Animal { 
breed: string; 


// 错误 : 使 用 数值 型 的 字符 串 索引 ， 有 时 会 得 到 完全 不 同 的 Animall 
interface SES { 
[x: number]: Animal; 


[x: string]: Dog; 


字符 串 索 引 签名 能 够 很 好 的 描述 dictionary 模式 ， 并 且 它 们 也 会 确保 所 有 属性 
与 其 返回 值 类 型 相 匹配 。 因为 字符 串 索 引 声明 

了 obj.property 和 obj["property"] 两 种 形式 都 可 以 。 下面 的 例子 

€» name 的 类 型 与 字符 串 索 引 类 型 不 匹配 ， 所 以 类 型 检查 器 给 出 一 个 错误 提示 


interface NumberDictionary { 


[index: string]: number; 
HK 3n] 


length: number; // T% * lengthznumber &# 
name: string // 错误 ，`name ` 的 类 型 与 索引 类 型 返回 值 的 类 型 不 匹配 


最 后 ， 你 可 以 将 索引 签名 设置 为 只 读 ， 这 样 就 防止 了 给 索引 赋值 : 


interface ReadonlyStringArray { 
readonly [index: number]: string; 


} 
let myArray: ReadonlyStringArray = ["Alice", "Bob"]; 


myArray[2] = "Mallory"; // error! 


你 不 能 设置 myArray[2] ， 因 为 索引 签名 是 只 读 的 。 


实现 接口 
与 C# 或 Java 里 接口 的 基本 作用 一 样 ，TypeScript 也 能 够 用 它 来 明确 的 强制 一 个 类 去 
SARA RA © 


interface ClockInterface { 
currentTime: Date; 


class Clock implements ClockInterface ( 
currentTime: Date; 
constructor(h: number, m: number) ( ) 


你 也 可 以 在 接口 中 描述 一 个 方法 ， 在 类 里 实现 它 ， 如 同 下 面 的 setrime 方法 一 
样 : 


interface ClockInterface { 
currentTime: Date; 
setTime(d: Date); 


class Clock implements ClockInterface { 
currentTime: Date; 
setTime(d: Date) { 
this.currentTime - d; 


j 
constructor(h: number, m: number) { } 
j 
接口 描述 了 类 的 公共 ， 而 不 是 公共 和 私有 两 部 分 。 它 不 会 帮 你 检查 类 是 否 具有 


某 些 私有 成 员 。 


类 静态 部 分 与 实例 部 分 的 区 别 


当 你 操作 类 和 接口 的 时 候 ， 你 要 知道 类 是 具有 两 个 类 型 的 : 静态 部 分 的 类 型 和 实例 
的 类 型 。 你 会 注意 到 ， 当 你 用 构造 器 签名 去 定义 一 个 接口 并 试图 定义 一 个 类 去 实现 
这 个 接口 时 会 得 到 一 个 错误 : 


interface ClockConstructor { 
new (hour: number, minute: number); 


class Clock implements ClockConstructor { 
currentTime: Date; 
constructor(h: number, m: number) { } 


这 里 因为 当 一 个 类 实现 了 一 个 接口 时 ， 只 对 其 实例 部 分 进行 类 型 检查 。 constructor 
存在 于 类 的 静态 部 分 ， 所 以 不 在 检查 的 范围 内 。 


因此 ， 我 们 应 该 直接 操作 类 的 静态 部 分 。 看 下 面 的 例子 ， 我 们 定义 了 两 个 接 
口 ，ClockConstructor 为 构造 吕 数 所 用 和 ClockInterface 为 实例 方法 所 用 。 
为 了 方便 我 们 定义 一 个 构造 函数 createClock ， 它 用 传 入 的 类 型 创建 实例 。 


interface ClockConstructor { 
new (hour: number, minute: number): ClockInterface; 


} 

interface ClockInterface { 
tick(); 

} 


function createClock(ctor: ClockConstructor, hour: number, minut 
e: number): ClockInterface ( 
return new ctor(hour, minute); 


class DigitalClock implements ClockInterface ( 
constructor(h: number, m: number) ( ) 
tick() { 
console.log("beep beep"); 


j 


class AnalogClock implements ClockInterface ( 
constructor(h: number, m: number) ( } 
tick() { 
console. Jog( tick tock”); 


Jet digital = createClock(DigitalClock, 12, 17); 
let analog = createClock(AnalogClock, 7, 32); 


因为 createClock 的 第 一 个 参数 是 ClockConstructor 类 型 ， 
在 createClock(AnalogClock, 7, 32) 里 ， 会 检查 AnalogClock 是 否 符合 
造 函 数 签名 。 


cy 


继承 接口 


和 类 一 样 ， 接 口 也 可 以 相互 继承 。 这 让 我 们 能 够 从 一 个 接口 里 复制 成 员 到 另 一 个 接 
口 里 ， 可 以 更 灵活 地 将 接口 分 割 到 可 重用 的 模块 里 。 


interface Shape { 
color: string; 


interface Square extends Shape ( 
sideLength: number; 


let square = <Square>{}; 
square.color - "blue"; 
square.sideLength = 10; 


一 个 接口 可 以 继承 多 个 接口 ， 创 建 出 多 个 接口 的 合成 接口 。 


interface Shape { 
color: string; 


interface PenStroke { 
penwidth: number; 


interface Square extends Shape, PenStroke { 
sideLength: number; 


let square = <Square>{}; 
square.color - "blue"; 
square.sideLength = 10; 
square.penwWidth = 5.0; 


先前 我 们 提 过 ， 接 口 能 够 描述 JavaScript 里 丰富 的 类 型 。 因 为 JavaScript 其 动态 灵 
活 的 特点 ， 有 时 你 会 希望 一 个 对 象 可 以 同时 具有 上 面 提 到 的 多 种 类 型 。 


一 个 例子 就 是 ， 一 个 对 象 可 以 同时 做 为 函数 和 对 象 使 用 ， 并 带 有 额外 的 属性 。 


interface Counter { 
(start: number): string; 
interval: number; 
reset(): void; 


function getCounter(): Counter { 
let counter = <Counter>function (start: number) { }; 
counter.interval = 123; 
counter.reset = function () { }; 
return counter; 


} 

let c = getCounter(); 
c(10); 

c.reset(); 


c.interval = 5.0; 


在 使 用 JavaScript 第 三 方 库 的 时 候 ， 你 可 能 需要 像 上 面 那样 去 完整 地 定义 类 型 。 


接口 继承 类 


当 接 口 继承 了 一 个 类 类 型 时 ， 它 会 继承 类 的 成 员 但 不 包括 其 实现 。 就 好 像 接 口 声 明 
了 所 有 类 中 存在 的 成 员 ， 但 并 没有 提供 具体 实现 一 样 。 接口 同样 会 继承 到 类 的 
private 和 protected 成 员 。 这 意味 着 当 你 创建 了 一 个 接口 继承 了 一 个 拥有 私有 或 受 
保护 的 成 员 的 类 时 ， 这 个 接口 类 型 只 能 被 这 个 类 或 其 子 类 所 实现 (implement) 。 


当 你 有 一 个 庞大 的 继承 结构 时 这 很 有 用 ， 但 要 指出 的 是 你 的 代码 只 在 子 类 拥有 特定 
属性 时 起 作用 。 除了 继承 自 基 类 ， 子 类 之 间 不 必 相 关联 。 例 : 


class Control { 
private state: any; 


interface SelectableControl extends Control { 
select(): void; 


class Button extends Control implements SelectableControl { 
select() { } 


Class TextBox extends Control { 
select() { } 


// Error: Property ‘state’ is missing in type ‘Image’. 
class Image implements SelectableControl { 
select() { } 


class Location { 


在 上 面 的 例子 里 ， SelectableControl 包含 了 Control 的 所 有 成 员 ， 包 括 私 有 
成 员 state 。 因为 state 是 私有 成 员 ， 所 以 只 能 够 是 Control 的 子 类 们 才能 
实现 SelectableControl 接口 。 因 为 只 有 control 的 子 类 才能 够 拥有 一 个 声明 
于 Control 的 私有 成 员 state ， 这 对 私有 成 员 的 兼容 性 是 必需 的 。 


在 Control 类 内 部 ， 是 允许 通过 SelectableControl 的 实例 来 访问 私有 成 

员 state 的 。 实际 上 ， SelectableControl 就 像 Control 一 样 ， 并 拥有 一 
个 select 方法 。 Button 和 TextBox 类 是 SelectableControl 的 子 类 (A 
为 它们 都 继承 自 Control 并 有 select 方法 ) ， 但 Image 和 Location 类 并 不 


是 这 样 的 。 


传统 的 JavaScript 程 序 使 用 函数 和 基于 原型 的 继承 来 创建 可 重用 的 组 件 ， 但 对 于 熟 
悉 使 用 面向 对 象 方式 的 程序 员 来 讲 就 有 些 琼 手 ， 因 为 他 们 用 的 是 基于 类 的 继承 并 且 
对 象 是 由 类 构建 出 来 的 。 从 ECMAScript 2015， 也 就 是 ECMAScript 6 开始 > 
JavaScript 程 序 员 将 能 够 使 用 基于 类 的 面向 对 象 的 方式 。 使 用 TypeScript， 我 们 人 允 
许 开 发 者 现在 就 使 用 这 些 特性 ， 并 且 编 译 后 的 JavaScript 可 以 在 所 有 主流 浏览 器 和 
平台 上 运行 ， 而 不 需要 等 到 下 个 JavaScript 版 本 。 


X 


下 面 看 一 个 使 用 类 的 例子 : 


class Greeter { 
greeting: string; 
constructor(message: string) { 
this.greeting = message; 


j 
greet() 1 

return "Hello, " + this.greeting; 
j 


let greeter = new Greeter("world"); 


如 果 你 使 用 过 C# 或 Java， 你 会 对 这 种 语法 非常 熟悉 。 我 们 声明 一 

个 Greeter 类 。 这 个 类 有 3 个 成 员 : 一 个 叫做 greeting 的 铬 性， 一 个 构造 函数 
和 一 个 greet 方法 。 

你 会 注意 到 ， 我 们 在 引用 任何 一 个 类 成 员 的 时 候 都 用 了 this 9 它 表示 我 们 访问 
的 是 类 的 成 员 。 


最 后 一 行 ， 我 们 使 用 new 构造 了 Greeter 类 的 一 个 实例 。 它 会 调用 之 前 定义 的 
构造 函数 ， 创 建 一 个 Greeter 类 型 的 新 对 象 ， 并 执行 构造 函数 初始 化 它 。 


继承 


在 TypeScript 里 ， 我 们 可 以 使 用 常用 的 面向 对 象 模式 。 基于 类 的 程序 设计 中 一 种 最 
基本 的 模式 是 允许 使 用 继承 来 扩展 现 有 的 类 。 


看 下 面 的 例子 : 


class Animal { 
move(distancelnMeters: number = 0) { 
console.log( Animal moved ${distanceInMeters}m. ~); 


class Dog extends Animal { 
bark() { 
console.log('Woof! Woof!'); 


const dog - new Dog(); 
dog.bark(); 
dog.move(10); 
dog.bark(); 


这 个 例子 展示 了 最 基本 的 继承 : 类 从 基 类 中 继承 了 属性 和 方法 。 这 里 ， Dog 是 一 
个 派生 类 ， 它 派生 自 Animal 基 类 ， 通 过 extends 关键 字 。 派生 类 通常 被 称 作 子 
类 ， 基 类 通常 被 称 作 超 类 。 

因为 Dog 继承 了 Animal 的 功能 ， 因 此 我 们 可 以 创建 一 个 Dog 的 实例 ， 它 能 

够 bark() 和 move() ° 


下 面 我 们 来 看 个 更 加 复杂 的 例子 。 


class Animal { 
name: string; 
constructor(theName: string) { this.name = theName; } 
move(distancelnMeters: number = 0) { 
console.log( ${this.name} moved ${distanceInMeters}m. ); 


class Snake extends Animal { 
constructor(name: string) { super(name); ) 
move(distanceInMeters - 5) ( 
console.log("Slithering..."); 
super.move(distanceInMeters); 


class Horse extends Animal { 
constructor(name: string) { super(name); ) 
move(distanceInMeters - 45) ( 
console.log("Galloping..."); 
super.move(distanceInMeters); 


let sam - new Snake("Sammy the Python"); 
let tom: Animal - new Horse("Tommy the Palomino"); 


sam.move(); 
tom.move(34); 


2 


这 个 例子 展示 了 一 些 上 面 没 有 提 到 的 特性 。 这 一 次 ， 我 们 使 用 extends 关键 字 创 
了 Animal 的 两 个 子 类 : Horse 和 Snake 。 


与 前 一 个 例子 的 不 同 点 是 ， 派 生 类 包含 了 一 个 构造 函数 ， 它 必须 调用 super() ， 
会 执行 基 类 的 构造 函数 。 而 且 ， 在 构造 函数 里 访问 this 的 属性 之 前 ， 我 们 一 
要 调用 super() 。 这 个 是 TypeScript 强 制 执 行 的 一 条 重要 规则 。 


` 
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这 个 例子 演示 了 如 何在 子 类 里 可 以 重 写 父 类 的 方法 。 Snake 类 和 Horse 类 都 创 
建 了 move 方法 ， 它 们 重 写 了 从 Animal 继承 来 的 move 方法 ， 使 得 move 方法 
根据 不 同 的 类 而 具有 不 同 的 功能 。 注意 ， 即 使 tom 被 声明 为 Animal 类 型 ， 但 因 
为 它 的 值 是 Horse ， 调 用 tom.move(34) 时 ， 它 会 调用 Horse 里 重 写 的 方法 : 


Slithering... 

Sammy the Python moved 5m. 
Galloping... 

Tommy the Palomino moved 34m. 


公共 ， 私 有 与 党 保护 的 修饰 香 


默认 为 public 


在 上 面 的 例子 里 ， 我 们 可 以 自由 的 访问 程序 里 定义 的 成 员 。 如 果 你 对 其 它 语言 中 的 
类 比较 了 解 ， 就 会 注意 到 我 们 在 之 前 的 代码 里 并 没有 使 用 public 来 做 修饰 ; 例 
如 ，C# 要 求 必 须 明 确 地 使 用 public 指定 成 员 是 可 见 的 。 在 TypeScript 里 ， 成 员 
都 默认 为 public 。 


你 也 可 以 明确 的 将 一 个 成 员 标记 成 public 。 我们 可 以 用 下 面 的 方式 来 重 写 上 面 


的 Animal 类 : 


class Animal { 
public name: string; 
public constructor(theName: string) { this.name = theName; } 
public move(distanceInMeters: number) { 
console.log( ${this.name} moved $([distancelInMeters)m.'); 


理解 private 


当成 员 被 标记 成 private 时 ， 它 就 不 能 在 声明 它 的 类 的 外 部 访问 。 比 如 : 


class Animal { 
private name: string; 
constructor(theName: string) { this.name = theName; } 


new Animal("Cat").name; // 错误 : 'name' 是 私有 的 ， 


TypeScript 使 用 的 是 结构 性 类 型 系统 。 当 我 们 比较 两 种 不 同 的 类 型 时 ， 并 不 在 乎 它 
们 从 何 处 而 来 ， 如 果 所 有 成 员 的 类 型 都 是 兼容 的 ， 我 们 就 认为 它们 的 类 型 是 兼容 
的 。 


然而 ， 当 我 们 比较 带 有 private 或 protected 成 员 的 类 型 的 时 候 ， 情 况 就 不 同 
Jo 如 果 其 中 一 个 类 型 里 包含 一 个 private 成员， 那么 只 有 当 另 外 一 个 类 型 中 也 
存在 这 样 一 个 private 成 员 ， 并 且 它 们 都 是 来 自 同一 处 声明 时 ， 我 们 才 认 为 这 两 
个 类 型 是 兼容 的 。 对 于 protected 成 员 也 使 用 这 个 规则 。 


下 面 来 看 一 个 例子 ， 更 好 地 说 明了 这 一 点 : 


class Animal { 
private name: string; 
constructor(theName: string) { this.name = theName; } 


class Rhino extends Animal { 
constructor() { super("Rhino"); } 


class Employee { 
private name: string; 
constructor(theName: string) { this.name = theName; } 


let animal = new Animal("Goat"); 
let rhino = new Rhino(); 
let employee = new Employee("Bob"); 


animal = rhino; 
animal = employee; // 错误 : Animal 4 Employee 不 兼容 ， 


这 个 例子 中 有 Animal fe Rhino 两 个 类 ， Rhino Æ Animal RH X 9 还 有 一 
个 Employee 类 ， 其 类 型 看 上 去 与 Animal 是 相同 的 。 我 们 创建 了 几 个 这 些 类 的 
实例 ， 并 相互 赋值 来 看 看 会 发 生 什么 。 AA Animal 和 Rhino 共享 了 来 

A Animal 里 的 私有 成 员 定 义 private name: string ， 因 此 它们 是 兼容 的 。 然 
而 Employee 却 不 是 这 样 。 当 把 Employee 赋值 给 Animal 的 时 候 ， 得 到 一 个 错 
误 ， 说 它们 的 类 型 不 兼容 。 尽 管 Employee 里 也 有 一 个 私有 成 员 name ， 但 它 明 
显 不 是 Animal 里 面 定义 的 那个 。 


理解 protected 


protected 修饰 符 与 private 修饰 符 的 行为 很 相似 ， 但 有 一 点 不 
同 ， protected 成 员 在 派生 类 中 仍然 可 以 访问 。 例 如 : 


class Person { 
protected name: string; 
constructor(name: string) { this.name = name; } 


class Employee extends Person { 
private department: string; 


constructor(name: string, department: string) { 
super (name) 
this.department = department; 


public getElevatorPitch() { 
return "Hello, my name is ${this.name} and I work in ${t 
his.department).'; 


j 


let howard - new Employee("Howard", "Sales"); 
console.log(howard.getElevatorPitch()); 
console.log(howard.name); // 错误 


注意 ， 我 们 不 能 在 Person 类 外 使 用 name ， 但 是 我 们 仍然 可 以 通 
ii Employee 类 的 实例 方法 访问 ， 因 为 Employee 是 由 Person 派生 而 来 的 。 


构造 函数 也 可 以 被 标记 成 protected 。 这 意味 着 这 个 类 不 能 在 包含 它 的 类 外 被 实 
例 化 ， 但 是 能 被 继承 。 比 如， 


class Person { 

protected name: string; 

protected constructor(theName: string) { this.name = theName 
i d 
j 
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// Employee 能 够 继承 Person 
class Employee extends Person { 
private department: string; 


constructor(name: string, department: string) { 
super (name); 
this.department - department; 


public getElevatorPitch() { 
return “Hello, my name is ${this.name} and I work in ${t 
his.department]).'; 


j 


let howard - new Employee("Howard", "Sales"); 
let john = new Person("John"); // 错误 : 'Person' 的 构造 函数 是 被 保护 
8j. 


readonly ?# ^f f 


你 可 以 使 用 readonly 关键 字 将 属性 设置 为 只 读 的 。 只 读 属性 必须 在 声明 时 或 构 
造 隐 数 里 被 初始 化 。 


class Octopus { 
readonly name: string; 
readonly numberOfLegs: number = 8; 
constructor (theName: string) { 
this.name = theName; 


} 
} 
let dad = new Octopus("Man with the 8 strong legs"); 
dad.name = "Man with the 3-piece suit"; // 错误 ! name 是 只 读 的 . 


参数 属性 


在 上 面 的 例子 中 ， 我 们 不 得 不 定义 一 个 受 保 护 的 成 员 name 和 一 个 构造 函数 参 

a theName 在 Person 类 里 ， 并 且 立 刻 将 theName 的 值 赋 给 name 。 这 种 情况 
经 常会 遇 到 。 参 数 属 性 可 以 方便 地 让 我 们 在 一 个 地 方 定义 并 初始 化 一 个 成 员 。 下 面 
的 例子 是 对 之 前 Animal 类 的 修改 版 ， 使 用 了 参数 属性 : 


class Animal { 
constructor(private name: string) { } 
move(distanceInMeters: number) ( 
console.log( ${this.name} moved $(distancelInMeters)m."); 


注意 看 我 们 是 如 何 舍弃 了 theName * REM XX EKA private name: 
string 参数 来 创建 和 初始 化 name 成 员 。 我 们 把 声明 和 赋值 合并 至 一 处 。 


参数 属性 通过 给 构造 函数 和 参数 添加 一 个 访问 限定 符 来 声明 。 使 用 private 限定 一 
个 参数 属性 会 声明 并 初始 化 一 个 私有 成 员 ; 对 于 public 和 protected 来 说 也 是 
ages 


GRE 


TypeScript 支 持 通过 getters/setters 来 截取 对 对 象 成 员 的 访问 。 它 能 帮助 你 有 效 的 控 
制 对 对 象 成 员 的 访问 。 


下 面 来 看 如 何 把 一 个 简单 的 类 改写 成 使 用 get fe set 。 首先 ， 我 们 从 一 个 没有 
使 用 存 取 器 的 例子 开始 © 


class Employee { 
fullName: string; 


let employee = new Employee(); 

employee.fullName - "Bob Smith"; 

if (employee.fullName) ( 
console.log(employee.fullName); 


我 们 可 以 随意 的 设置 fullName » RCFE BARN ^ VERRAT HA AMM © 


下 面 这 个 版 本 里 ， 我 们 先 检查 用 户 密 码 是 否 正确 ， 然 后 再 允许 其 修改 员工 信息 。 我 
们 把 对 fullname 的 直接 访问 改 成 了 可 以 检查 密码 的 set 方法 。 我 们 也 加 了 一 
个 get 方法 ， 让 上 面 的 例子 仍然 可 以 工作 。 


let passcode = "secret passcode"; 


class Employee { 
private _fullName: string; 


get fullName(): string { 
return this._fullName; 


} 
set fullName(newName: string) { 
if (passcode && passcode == "secret passcode") { 
this._fullName = newName; 
} 
else { 
console.log("Error: Unauthorized update of employee!" 
); 
} 


let employee = new Employee(); 

employee.fullName = "Bob Smith"; 

if (employee.fullName) { 
alert(employee.fullName); 
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我 们 可 以 修改 一 下 密码 ， 来 验证 一 下 存 取 器 是 否 是 工作 的 。 当 密码 不 对 时 ， 会 提示 
我 们 没有 权限 去 修改 员工 。 


对 于 存 取 器 有 下 面 几 点 需要 注意 的 : 


首先 ， 存 取 器 要 求 你 将 编译 器 设置 为 输出 ECMAScript 5 或 更 高 。 不 支持 降级 到 
ECMAScript 3。 其 次 ， 只 带 有 get 不 带 有 set 的 存 取 器 自动 被 推断 

为 readonly 。 这 在 从 代码 生成 .d.ts 文件 时 是 有 帮助 的 ， 因 为 利用 这 个 属性 的 
用 户 会 看 到 不 允许 够 改变 它 的 值 。 


静态 属性 


到 目前 为 止 ， 我 们 只 讨论 了 类 的 实例 成 员 ， 那 些 仅 当 类 被 实例 化 的 时 候 才 会 被 初始 
化 的 属性 。 我 们 也 可 以 创建 类 的 静态 成 员 ， 这 些 属 性 存在 于 类 本 身上 面 而 不 是 类 的 
实例 上 。 在 这 个 例子 里 ， 我 们 使 用 static 定义 origin ， 因 为 它 是 所 有 网 格 都 
会 用 到 的 属性 。 每 个 实例 想 要 访问 这 个 属性 的 时 候 ， 都 要 在 origin 前 面 加 上 类 

名 。 如同 在 实例 属性 上 使 用 this. 前 级 来 访问 属性 一 样 ， 这 里 我 们 使 

用 Grid. 来 访问 静态 属性 。 


class Grid { 
static origin = {x: 0, y: 0}; 
calculateDistanceFromOrigin(point: (x: number; y: number;)) 


{ 
let xDist = (point.x - Grid.origin.x); 
let yDist = (point.y - Grid.origin.y); 
return Math.sqrt(xDist * xDist + yDist * yDist) / this.s 
cale; 
} 
constructor (public scale: number) { } 
} 


let grid1 = new Grid(1.0); // 1x scale 
let grid2 = new Grid(5.0); // 5x scale 


console.log(grid1.calculateDistanceFromOrigin({x: 10, y: 10})); 
console.log(grid2.calculateDistanceFromOrigin({x: 10, y: 10})); 
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抽象 类 做 为 其 它 派 生 类 的 基 类 使 用 。 它们 一 般 不 会 直接 被 实例 化 。 不同 于 接口 ， 
抽象 类 可 以 包 侈 成 员 的 实现 细节 。 abstract 关键 字 是 用 于 定义 抽象 类 和 在 抽象 
类 内 部 定义 抽象 方法 。 


abstract class Animal { 
abstract makeSound(): void; 
move(): void { 
console.log('roaming the earch...'); 


抽象 类 中 的 抽象 方法 不 包含 具体 实现 并 且 必须 在 派生 类 中 实现 。 抽象 方法 的 语法 与 
接口 方法 相似 。 两 者 都 是 定义 方法 签名 但 不 包含 方法 体 。 然 而 ， 抽 象 方法 必须 包 
4 abstract 关键 字 并 且 可 以 包含 访问 修饰 符 。 


abstract class Department { 


constructor(public name: string) { 


} 


printName(): void { 
console.log('Department name: ' + this.name); 


abstract printMeeting(): void; // 必须 在 派生 类 中 实现 


class AccountingDepartment extends Department { 


constructor() { 
super('Accounting and Auditing'); // 在 派生 类 的 构造 函数 中 必 
须 调用 super() 
} 


printMeeting(): void { 
console.log('The Accounting Department meets each Monday 
at 10am.'); 


j 


generateReports(): void ( 
console.log('Generating accounting reports...'); 


let department: Department; // 允许 创建 一 个 对 抽象 类 型 的 引用 
department = new Department(); // 错误 : 不 能 创建 一 个 抽象 类 的 实 
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department = new AccountingDepartment(); // Aa — Sii RF 
例 化 和 赋值 

department.printName(); 

department.printMeeting(); 

department.generateReports(); // 错误 : 方法 在 声明 的 抽象 类 中 不 存在 


高 级 技巧 


构造 函数 


当 你 在 TypeScript 里 声明 了 一 个 类 的 时 候 ， 实 际 上 同时 声明 了 很 多 东西 。 首先 就 是 
类 的 实例 的 类 型 。 


class Greeter { 
greeting: string; 
constructor(message: string) { 
this.greeting = message; 


} 
greet() { 

return "Hello, " + this.greeting; 
} 


let greeter: Greeter; 
greeter = new Greeter("world"); 
console. log(greeter.greet()); 


这 里 ， 我 们 写 了 let greeter: Greeter * SVX Greeter 类 的 实例 的 类 型 
是 Greeter ° 这 对 于 用 过 其 它 面 向 对 象 语言 的 程序 员 来 讲 已 经 是 老 习 惯 了 。 


我 们 也 创建 了 一 个 叫做 构造 函数 的 值 。 这 个 函数 会 在 我 们 使 用 new 创建 类 实例 的 
时 候 被 调用 。 下面 我 们 来 看 看 ， 上 面 的 代码 被 编译 成 JavaScript 后 是 什么 样子 的 : 


let Greeter = (function () { 

function Greeter(message) { 
this.greeting = message; 

} 

Greeter.prototype.greet = function () { 
return "Hello, " + this.greeting; 

a 

return Greeter; 


HO; 


let greeter; 
greeter = new Greeter ("world"); 
console.log(greeter.greet()); 


上 面 的 代码 里 ， let Greeter 将 被 赋值 为 构造 函数 。 当 我 们 调用 new 并 执行 了 
这 个 函数 后 ， 便 会 得 到 一 个 类 的 实例 。 这 个 构造 函数 也 包含 了 类 的 所 有 静 态 属 性 。 
换个 角度 说 ， 我 们 可 以 认为 类 具有 实例 部 分 与 静态 部 分 这 两 个 部 分 


让 我 们 稍微 改写 一 下 这 个 例子 ， 看 看 它们 之 间 的 区 别 : 


class Greeter { 
static standardGreeting = "Hello, there"; 
greeting: string; 
greet() { 
if (this.greeting) { 
return "Hello, " + this.greeting; 


} 
else { 

return Greeter.standardGreeting; 
} 


let greeter1: Greeter; 
greeteri = new Greeter(); 
console. log(greeter1.greet()); 


let greeterMaker: typeof Greeter = Greeter; 
greeterMaker.standardGreeting = "Hey there!"; 


let greeter2: Greeter = new greeterMaker(); 
console. log(greeter2.greet()); 


这 个 例子 里 ， greeteri 与 之 前 看 到 的 一 样 。 我 们 实例 化 Greeter 类 ， 并 使 用 
这 个 对 象 。 与 我 们 之 前 看 到 的 一 样 。 


再 之 后 ， 我 们 直接 使 用 类 。 我 们 创建 了 一 个 叫做 greeterMaker 的 变量 。 这 个 
量 保存 了 这 个 类 或 者 说 保存 了 类 构造 函数 。 然后 我 们 使 用 typeof Greeter ，:; 
思 是 取 Greeter 类 的 类 型 ， 而 不 是 实例 的 类 型 。 ue "A 

R Greeter 标识 符 的 类 型 "， 也 就 是 构造 函数 的 类 型 。 这 个 类 型 包含 了 类 的 所 有 
静态 成 员 和 构造 函数 。 之 后 ， 就 和 前 面 一 样 ， 我 们 在 greeterMaker 上 使 

用 new ， 创 建 Greeter 的 实例 。 
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把 类 当做 接口 使 用 


如 上 一 节 里 所 讲 的 ， 类 定义 会 创建 两 个 东西 : 类 的 实例 类 型 和 一 个 构造 函数 。 因为 
类 可 以 创建 出 类 型 ， 所 以 你 能 够 在 允许 使 用 接口 的 地 方 使 用 类 。 


class Point { 
x: number; 
y: number; 


interface Point3d extends Point { 
z: number; 


let point3d: Pointed = (x: 4, y: 2, z: 3}; 


函数 是 JavaScript 应 用 程序 的 基础 。 它 帮 助 你 实现 抽象 层 ， 模 拟 类 ， 信 息 隐 藏 和 模 
块 。 在 TypeScript 里 ， 虽 然 已 经 支持 类 ， 命 名 空间 和 模块 ， 但 部 数 仍然 是 主要 的 定 
义 行为 的 地 方 。TypeScript 为 JavaScript 函 数 添加 了 额外 的 功能 ， 让 我 们 可 以 更 容 
H 
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选择 适合 应 用 程序 的 方式 ， 不 论 是 定义 一 系列 API 函 数 还 是 只 使 用 一 次 的 函数 。 
通过 下 面 的 例子 可 以 迅速 回想 起 这 两 种 JavaScript 中 的 函数 : 
// Named function 


function add(x, y) { 
return x + y; 


// Anonymous function 
let myAdd = function(x, y) { return x + y; }; 
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获 : 了 这 些 变 量 。 至 于 为 什么 可 以 这 样 做 以 及 其 中 的 利 头 超出 了 本 文 的 范围 ， 但 是 
理解 这 个 机 制 对 学 习 JavaScript 和 TypeScript 会 很 有 帮助 。 


let z = 100; 


function» addioZ(x, y) 4 
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为 函数 定义 类 型 
让 我 们 为 上 面 那 个 函数 添加 类 型 : 


function add(x: number, y: number): number { 
return x + y; 


let myAdd = function(x: number, y: number): number { return x + 
y; }; 


我 们 可 以 给 每 个 参数 添加 类 型 之 后 再 为 函 NRA A tie SEXUS = Typoscript Eb 
根据 返回 语句 自动 推断 出 返回 值 类 型 ， 因 此 我 们 通常 省 略 它 。 


书写 完整 函数 类 型 


现在 我 们 已 经 为 函数 指定 了 类 型 ， 下 面 让 我 们 写 出 函数 的 完整 类 


ed 


o 


let myAdd: (x:number, y:number) => number = 
function(x: number, y: number): number ( return x + y; Y; 


函数 类 型 包含 两 部 分 : 参数 类 型 和 返回 值 类 型 。 当 写 出 完整 函数 类 型 的 时 候 ， 这 两 
部 分 都 是 gu 我 们 以 参数 列表 的 形式 写 出 参数 类 型 ， 为 每 个 参数 指定 一 个 名 字 
和 类 型 。 这 个 名 字 只 是 为 了 增加 可 读 性 。 我们 也 可 以 这 么 写 : 


let myAdd: (baseValue: number, increment: number) => number = 
function(x: number, y: number): number { return x + y; Y; 


只 要 参数 类 型 是 匹配 的 ， 那 么 就 认为 它 是 有 效 的 函数 类 型 ， 而 不 在 乎 参数 名 是 否 正 


第 二 部 分 是 返 辐 值 类 型 。 对 于 返回 值 ， ane i Bk Fo HE el fs KAZ AAR A => ) 符 
号 ， 使 之 清晰 明了 。 如 之 前 提 到 的 ， 返 回 值 类 型 是 函数 类 型 的 必要 部 分 ， 如 果 函 数 
没有 返回 任何 值 ， 你 也 必须 指 newer void 而 不 能 留 空 。 


参数 类 型 和 返回 值 组 成 的 。 函数 中 使 用 的 捕获 变量 不 会 体现 在 类 
型 里 。 实际 上 ， 这 些 变量 是 函数 的 隐藏 状态 并 不 是 组 成 API 的 一 部 分 。 
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尝试 这 个 例子 的 时 候 ， 你 会 发 现 如 果 你 在 赋值 语句 的 一 边 指定 了 类 型 但 是 另 一 边 没 
有 类 型 的 话 ，TypeScript 编 译 器 会 自动 识别 出 类 型 : 


// myAdd has the full function type 
let myAdd = function(x: number, y: number): number { return x + 
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// The parameters x and "y^ have the type number 
let myAdd: (baseValue: number, increment: number) -» number - 
Lunction(x, Y) T return oco vo p 


这 叫做 “ 按 上 下 文 归 类 ”， 是 类 型 推论 的 一 种 。 它 帮 助 我 们 更 好 地 为 程序 指定 类 型 。 


可 选 参 数 和 默认 参数 


TypeScript 里 的 每 个 函数 参数 都 是 必须 的 。 这 不 是 指 不 能 传 

i$ null 或 undefined 作为 参数 ， 而 是 说 编译 器 检查 用 户 是 否 为 每 个 参数 都 传 入 
了 值 。 编 译 器 还 会 假设 只 有 这 些 参数 会 被 传递 进 函 数 。 简短 地 说 ， 传 递 给 一 个 函 
een yee 数 期 望 的 参数 个 数 一 致 。 


function buildName(firstName: string, lastName: string) { 
return firstName + " " + lastName; 


let resulti = buildName("Bob"); // error, too f 
ew parameters 

let result2 = buildName("Bob", "Adams", "Sr."); // error, too m 
any parameters 

let result3 - buildName("Bob", "Adams"); // ah, just rig 
ht 


JavaScript 里 ， 每 个 参数 都 是 可 选 的 ， 可 传 可 不 传 。 没 传 参 的 时 候 ， 它 的 值 就 是 
undefined » 在 TypeScript 里 我 们 可 以 在 参数 名 旁 使 用 ? 实现 可 选 参数 的 功能 。 比 
如 ， 我 们 想 让 last name 是 可 选 的 : 


function buildName(firstName: string, lastName?: string) { 
if (lastName) 
return firstName + " " + lastName; 
else 
return firstName; 


let resulti = buildName("Bob"); // works correctly now 

let result2 = buildName("Bob", "Adams", "Sr."); // error, too m 
any parameters 

let result3 = buildName("Bob", "Adams"); // ah, just right 


可 选 参 数 必 须 跟 在 必须 参数 后 面 。 如 果 上 例 我 们 想 让 first nme TAi > MAB 
必须 调整 它们 的 位 置 ， 把 first name 放 在 后 面 。 


在 TypeScript 里 ， 我 们 也 可 以 为 参数 提供 一 个 默认 值 当 用 户 没有 传递 这 个 参数 或 传 
递 的 值 是 undefined He 它们 叫做 有 默认 初始 化 值 的 参数 。 让 我 们 修改 上 例 ， 
把 last name 的 默认 值 设置 为 "Smith" 。 


function buildName(firstName: string, lastName = "Smith") { 
return firstName + " " + lastName; 

j 

let resulti = buildName("Bob"); // works correc 

tly now, returns "Bob Smith" 

let result2 - buildName("Bob", undefined); // still works, 


also returns "Bob Smith" 

let result3 = buildName("Bob", "Adams", "Sr."); // error, too m 
any parameters 

let result4 - buildName("Bob", "Adams"); // ah, just rig 
ht 


在 所 有 必须 参数 后 面 的 带 默 认 初 始 化 的 参数 都 是 可 选 的 ， 与 可 选 参数 一 样 ， 在 调用 
函数 的 时 候 可 以 省 略 。 也 就 是 说 可 选 参 数 与 末尾 的 默认 参数 共享 参数 类 型 。 
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JEJE 


buildName(firstName: string, lastName?: string) { 


} 
和 
function buildName(firstName: string, lastName = "Smith") { 
OA 
j 


共享 同样 的 类 型 (firstName: string, lastName?: string) => string » X 


认 参 数 的 默认 值 消失 了 ， 只 保留 了 它 是 一 个 可 选 参数 的 信 


息 © 
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与 普通 可 选 参数 不 同 的 是 ， 带 默认 值 的 参数 不 需要 放 在 必须 参数 的 后 面 。 如 果 带 默 
认 值 的 参数 出 现在 必须 参数 前 面 ， 用 户 必 须 明 确 的 传 入 undefined 值 来 获得 默认 
值 。 人 例如， 我们 重 写 最 后 一 个 例子 ， 让 firstName 是 带 默 认 值 的 参数 : 


function buildName(firstName = "Will", lastName: string) { 


return firstName + " " + lastName; 


let resulti = buildName("Bob"); 

ew parameters 

let result2 - buildName("Bob", "Adams", "Sr." 
any parameters 

let result3 - buildName("Bob", "Adams"); 

urns "Bob Adams" 

let result4 - buildName(undefined, "Adams"); 
urns "Will Adams" 


剩余 参数 


必要 参数 ， 默 认 参 数 和 可 选 参数 有 个 共同 点 : 它们 表示 某 
时 操作 多 个 参数 ， 或 者 你 并 不 知道 会 有 多 少 参 数 传递 进来 
以 使 用 arguments 来 访问 所 有 传 入 的 参数 。 


// error, too f 
); // error, too m 
// okay and ret 


// okay and ret 


一 个 参数 。 有 时 ， 你 想 同 
。 在 JavaScript 里 ， 你 可 


在 TypeScript 里 ， 你 可 以 把 所 有 参数 收集 到 一 个 变量 里 : 


function buildName(firstName: string, ...restOfName: string[]) { 
return firstName + " " + restOfName.join(" "); 


j 


let employeeName = buildName("Joseph", "Samuel", "Lucas", "MacKi 
nzie"); 


剩余 参数 会 被 当做 个 数 不 限 的 可 选 参数 。 可 以 一 个 都 没有 ， 同 样 也 可 以 有 任意 个 。 
编译 器 创建 参数 数组 ， 名 字 是 你 在 省 略 号 ( ,.，) 后 面 给 定 的 名 字 ， 你 可 以 在 函 
数 体内 使 用 这 个 数组 。 


这 个 省 略 号 也 会 在 带 有 剩余 参数 的 函数 类 型 定义 上 使 用 到 : 


function buildName(firstName: string, ...restOfName: string[]) { 
return firstName + " " + restOfName.join(" "); 
} 
let buildNameFun: (fname: string, ...rest: string[]) => string = 
buildName; 
this 


学 习 如 何在 JavaScript 里 正确 使 用 this 就 好 比 一 场 成 年 礼 。 由 于 TypeScript 是 
Pelee > TypeScript 程 序 员 也 需要 弄 清 this 工作 机 制 并 且 当 有 bug 的 时 
必 能 够 找 出 错误 所 在 。 幸运 的 是 ，TypeScript 能 通知 你 错误 地 使 用 了 this 的 地 

方 。 如 果 你 想 了 解 JavaScript 里 的 this 是 如 何 工作 的 ， 那 么 首先 阅读 Yehuda 
Katz 写 的 Understanding JavaScript Function Invocation and "this"。 Yehuda 的 文 
Hip AMT this 的 内 部 工作 原理 ， 因 此 我 们 这 里 只 做 简单 介绍 。 


this 和 箭头 函数 


JavaScript 里 ， this 的 值 在 函数 被 调用 的 时 候 才 会 指定 。 这 是 个 既 强 大 又 灵活 的 
特点 ， 但 是 你 需要 花 点 时 间 弄 清楚 函数 调用 的 上 下 文 是 什么 。 但 众所周知 ， 这 不 是 
一 件 很 简单 的 事 ， 尤 其 是 在 返回 一 个 函数 或 将 函数 当做 参数 传递 的 时 候 。 


下 面 看 一 个 例子 : 


let deck = { 
suits: ["hearts", "spades", "clubs", "diamonds"], 
cards: Array(52), 
createCardPicker: function() { 
return function() { 
let pickedCard = Math.floor(Math.random() * 52); 
let pickedSuit = Math.floor(pickedCard / 13); 


return {suit: this.suits[pickedSuit], card: pickedCa 
rd % 13}; 
} 


let cardPicker = deck.createCardPicker(); 
let pickedCard = cardPicker(); 


alert("card: " + pickedCard.card + " of " + pickedCard.suit); 


可 以 看 到 createcardPicker 是 个 函数 ， 并 且 它 又 返回 了 一 个 函数 。 如 果 我 们 尝 
试 运行 这 个 程序 ， 会 发 现 它 并 没有 弹出 对 话 框 而 是 报错 了 。 

A createCardPicker 返回 的 函数 里 的 this 被 设置 成 了 window 而 不 

是 deck 对 象 。 因为 我 们 只 是 独立 的 调用 了 cardPicker() 。 顶级 的 非 方法 式 调 
用 会 将 this A window 。 (注意 :在 严格 模式 下 ， this 为 undefined 而 


不 是 window ) ° 


为 了 解决 这 个 问题 ， 我 们 可 以 在 函数 被 返回 时 就 绑 好 正确 的 this 。 这 样 的 话 ， 
无 论 之 后 怎么 使 用 它 ， 都 会 引用 绑 定 的 "deck' 对 象 。 我们 需要 改变 函数 表达 式 来 使 
用 ECMAScript 6 箭头 语法 。 箭头 函数 能 保存 函数 创建 时 的 this 值 ， 而 不 是 调用 
时 的 值 : 


let deck = { 
suits: ["hearts", "spades", "clubs", "diamonds"], 
cards: Array(52), 
createCardPicker: function() { 
// NOTE: the line below is now an arrow function, allowi 
ng us to capture 'this' right here 
return () => { 
let pickedCard = Math.floor(Math.random() * 52); 
let pickedSuit = Math.floor(pickedCard / 13); 


return {suit: this.suits[pickedSuit], card: pickedCa 
rd % 13}; 


} 


let cardPicker = deck.createCardPicker(); 
let pickedCard = cardPicker(); 


alert("card: " + pickedCard.card + " of " + pickedCard. suit); 


更 好 事情 是 ，TypeScript 会 警告 你 犯 了 一 个 错误 ， 如 果 你 给 编译 器 设置 了 -- 
noImplicitThis 标记 。 它 会 指出 this.suits[pickedsuit] 里 的 this 的 类 型 
为 any ° 


this 参数 


TS) this.suits[pickedsuit] 的 类 型 依 昌 为 any ° 这 是 因为 this 来 
自 对 象 字面 量 里 的 函数 表达 式 。 修改 的 方法 是 ， 提 供 一 个 显 式 的 this 参数 。 
this 参数 是 个 假 的 参数 ， 它 出 现在 参数 列表 的 最 前 面 : 


Function 1 (chis: void) 


// make sure ‘this is unusable in this standalone function 


让 我 们 往 例 子 里 添加 一 些 接口 ， Card 和 Deck ， 让 类 型 重用 能 够 变 得 清晰 简单 
we: 


interface Card { 
súrt: string; 
card: number; 
} 
interface Deck { 
suits: String il; 
cards: number[]; 
createCardPicker(this: Deck): () => Card; 


let deck: Deck = { 
suits: ["hearts", "spades", "clubs", "diamonds"], 
cards: Array(52), 
// NOTE: The function now explicitly specifies that its call 
ee must be of type Deck 
createCardPicker: function(this: Deck) { 
return () = { 
let pickedCard = Math.floor(Math.random() * 52); 
let pickedSuit = Math.floor(pickedCard / 13); 


return {suit: this.suits[pickedSuit], card: pickedCa 
rd % 13}; 


} 


let cardPicker = deck.createCardPicker(); 
let pickedCard = cardPicker(); 


alert("card: " + pickedCard.card + " of " + pickedCard.suit); 


现在 TypeScript 知 道 createCardPicker 期 望 在 某 个 Deck 对 象 上 调用 。 也 就 是 
说 this Æ Deck 类 型 的 ， 而 非 any ， 因 此 --noImplicitThis 不 会 报错 了 。 


回调 函数 里 的 this 参数 


当 你 将 一 个 函数 传递 到 某 个 库 函 数 里 在 稍 后 被 调用 时 ， 你 可 能 也 见 到 过 回调 函数 里 
的 this 会 报错 。 因为 当 回 调 函 数 被 调用 时 ， 它 会 被 当成 一 个 普通 函数 调 
用 ， this 4% undefined » 稍 做 改动 ， 你 就 可 以 通过 this 参数 来 避免 错 


误 。 首先 ， 库 函数 的 作者 要 指定 this HRA: 


interface UIElement { 
addClickListener(onclick: (this: void, e: Event) => void): v 
OL: 


} 


this: void 意味 着 addClickListener #1% onclick 是 一 个 函数 且 它 不 需要 
一 个 this 类 型 。 然后， 为 调用 代码 里 的 this 添加 类 型 注解 : 


class Handler { 
info: string: 
onClickBad(this: Handler, e: Event) { 
// oops, used this here. using this callback would crash 
at runtime 
this.info = e.message; 


} 
let h = new Handler(); 


uiElement.addClickListener(h.onClickBad); // error! 


指定 了 this 类 型 后 ， 你 显 式 声明 onclickBad 必须 在 Handler 的 实例 上 调用 。 
然后 TypeScript 会 检测 到 addclickListener ZR AAAA this: void 。 改 
变 this 类 型 来 修复 这 个 错误 : 


class Handler { 
info: string; 
onClickGood(this: void, e: Event) { 
// can't use this here because it's of type void! 
console.log('clicked!'); 


} 
let h = new Handler(); 


uiElement.addClickListener(h.onClickGood); 


因为 onClickGood 指定 了 this 类 型 为 void ， 因 此 传 
递 addClickListener 是 合法 的 。 当 然 了 ， 这 也 意味 着 不 能 使 用 this.info .如 
果 你 两 者 都 想 要 ， 你 不 得 不 使 用 箭头 函数 了 : 


class Handler { 
info: string; 
onClickGood = (e: Event) => { this.info = e.message } 


这 是 可 行 的 因为 箭头 函数 不 会 捕获 this ， 所 以 你 总 是 可 以 把 它们 传 给 期 

#@ this: void 的 函数 。 缺点 是 每 个 Handler 对 象 都 会 创建 一 个 箭头 函数 。 X 
一 方面 ， 方 法 只 会 被 创建 一 次 ， 添 加 到 Handler 的 原型 链 上 。 Men 

同 Handler 对 象 间 是 共享 的 。 


重 载 


JavaScript 本 身 是 个 动态 语言 。 JavaScript 里 函数 根据 传 入 不 同 的 参数 而 返回 不 同 
类 型 的 数据 是 很 常见 的 。 


let suits = ["hearts", "spades", "clubs", "diamonds"]; 


function pickCard(x): any { 
// Check to see if we're working with an object/array 
// if so, they gave us the deck and we'll pick the card 
if (typeof x == "object") { 
let pickedCard = Math.floor(Math.random() * x.length); 
return pickedCard; 


} 
// Otherwise just let them pick the card 
else if (typeof x == "number") { 
let pickedSuit = Math.floor(x / 13); 
return { suit: suits[pickedSuit], card: x % 13 }; 
} 


let myDeck = [{ suit: "diamonds", card: 2 }, { suit: "spades", c 
ard: 10 }, f suit: "hearts", card: 4 J|; 

let pickedCard1 = myDeck[pickCard(myDeck)]; 

alert("card: " + pickedCardi.card + " of " + pickedCard1.suit); 


let pickedCard2 = pickCard(i5); 
alert("card: " + pickedCard2.card + " of " + pickedCard2.suit); 


pickCard 方法 根据 传 入 参数 的 不 同 会 返回 两 种 不 同 的 类 型 。 如 果 传 入 的 是 代表 
纸牌 的 对 象 ， 函 数 作 用 是 从 中 抓 一 张 牌 。 如 果 用 户 想 抓 牌 ， 我 们 告诉 他 抓 到 了 什么 
牌 。 但 是 这 怎么 在 类 型 系统 里 表示 呢 。 


方法 是 为 同一 个 函数 提供 多 个 函数 类 型 定义 来 进行 函数 重 载 。 编译 器 会 根据 这 个 列 
表 去 处 理 有 函数 的 调用 。 下 面 我 们 来 重 载 pickcard 函数 。 


let 


suits = ["hearts", "spades", "clubs", "diamonds"]; 


function pickCard(x: fsuit: string; card: number; }[]): number; 


function pickCard(x: number): {suit: string; card: number; }; 


function pickCard(x): any { 


// Check to see if we're working with an object/array 
// if so, they gave us the deck and we'll pick the card 
if (typeof x == "object") { 
let pickedCard = Math.floor(Math.random() * x.length); 
return pickedCard; 
} 
// Otherwise just let them pick the card 
else if (typeof x == "number") { 
let pickedSuit = Math.floor(x / 13); 
return { suit: suits[pickedSuit], card: x % 13 }; 


} 
} 
let myDeck = [{ suit: "diamonds", card: 2 }, { suit: "Spades", c 
ard: 10 }, { suit: "hearts", card: 4 }]; 
let pickedCard1 = myDeck[pickCard(myDeck) ]; 
alert("card: " + pickedCardi.card + " of " + pickedCard1.suit); 
let pickedCard2 = pickCard(15); 
alert("card: " + pickedCard2.card + " of " + pickedCard2.suit); 


这 样 改变 后 ， 重 载 的 pickcard 函数 在 调用 的 时 候 会 进行 正确 的 类 型 检查 。 


Be A6 


为 了 让 编译 器 能 够 选择 正确 的 检查 类 型 ， 它 与 JavaScript 里 的 处 理 流程 相似 。 C& 
找 重 载 列 表 ， 尝 试 使 用 第 一 个 重 载 定 义 。 如 果 匹 配 的 话 就 使 用 这 个 。 因 此 ， 在 定 
义 重 载 的 时 候 ， 一 定 要 把 最 精确 的 定义 放 在 最 前 面 。 


LEE 
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function pickCard(x): any 并 不 是 重 载 列 表 的 一 部 分 ， 因 此 这 里 只 有 


两 个 重 载 : 一 个 是 接收 对 象 另 一 个 接收 数字 。 以 其 它 参数 调用 pickcard 会 产生 


错误 。 


软件 工程 中 ， 我 们 不 仅 要 创建 一 致 的 定义 良好 的 API， 同 时 也 要 考虑 可 重用 性 。 m 
件 不 仅 能 够 支持 当前 的 数据 类 型 ， 同 时 也 能 支持 未 来 的 数据 类 型 ， 这 在 创建 大 型 系 
统 时 为 你 提供 了 十 分 灵活 的 功能 。 


在 像 C# 和 Java 这 样 的 语言 中 ， 可 以 使 用 泛 型 来 创建 可 重用 的 组 件 ， 一 个 组 件 可 以 
支持 多 种 类 型 的 数据 。 这 样 用 户 就 可 以 以 自己 的 数据 类 型 来 使 用 组 件 。 


2% Z Hello World 
下 面 来 创建 第 一 个 使 用 泛 型 的 例子 : identity X o 这 个 函数 会 返回 任何 传 入 它 的 
值 。 你 可 以 把 这 个 函数 当成 是 echo 命令 。 


不 用 泛 型 的 话 ， 这 个 函数 可 能 是 下 面 这 样 : 


function identity(arg: number): number { 
return arg; 


或 者 ， 我 们 使 用 any 类 型 来 定义 函数 : 


function identity(arg: any): any { 
return arg; 


使 用 any 类 型 会 导致 这 个 函数 可 以 接收 任何 类 型 的 arg KH? MHREAT HE 
信息 : 传 入 的 类 型 与 返回 的 类 型 应 该 是 相同 的 。 如果 我 们 传 入 一 个 数字 ， 我 们 只 知 
道 任何 类 型 的 值 都 有 可 能 被 返回 。 


因此 ， 我 们 需要 一 种 方法 使 返回 值 的 类 型 与 传 入 参数 的 类 型 是 相同 的 。 这 里 ， 我 们 
使 用 了 类 型 变量 ， 它 是 一 种 特殊 的 变量 ， 只 用 于 表示 类 型 而 不 是 值 。 


FUNCTION Adentity<t>(arg: T): 人 
return arg; 


我 们 给 jdentity 添 加 了 类 型 变量 T 9 T 帮助 我 们 捕获 用 户 传 入 的 类 型 〈 比 

如 : number ) ， 之 后 我 们 就 可 以 使 用 这 个 类 型 。 之 后 我 们 再 次 使 用 了 T 当做 返 
回 值 类 型 。 现 在 我 们 可 以 知道 参数 类 型 与 返回 值 类 型 是 相同 的 了 。 这 允许 我 们 跟踪 
函数 里 使 用 的 类 型 的 信息 。 


我 们 把 这 个 版 本 的 identity 函数 叫做 泛 型 ， 因 为 它 可 以 适用 于 多 个 类 型 。 不 同 
cl, any ， 它 不 会 丢失 信息 ， 像 第 一 个 例子 那 像 保持 准确 性 ， 传 入 数值 类 型 并 
返回 数值 类 型 。 


我 们 定义 了 泛 型 函数 后 ， 可 以 用 两 种 方法 使 用 。 第 一 种 是 ， 传 入 所 有 的 和 参数， 包含 
类 型 参数 : 


let output = identity<string>("myString"); // type of output wi 
MEDER Ss Trgi 


这 里 我 们 明确 的 指定 了 T 是 string 类 型 ， 并 做 为 一 个 参数 传 给 函数 ， 使 用 
了 <> 括 起 来 而 不 是 () ° 


第 二 种 方法 更 普遍 。 利 用 了 类 型 推论 -- 即 编译 器 会 根据 传 入 的 参数 自动 地 帮助 我 们 
确定 T 的 类 型 : 


let output = identity("myString"); // type of output will be 's 
tring' 


注意 我 们 没 必 要 使 用 尖 括 号 ( <> ) 来 明确 地 传 入 类 型 ; 编译 器 可 以 查 

看 myString 的 值 ， T 设置 为 它 的 类 型 。 类 型 推论 帮助 我 们 保持 代码 精简 
和 高 可 读 性 。 如 果 编 译 器 不 能 够 自 ini eii ， 只 能 像 上 面 那样 明确 的 传 
入 下 的 类 型 ， 在 一 些 复 杂 的 XT: 可 能 出 现 的 。 


使 用 泛 型 变量 


使 用 泛 型 创建 像 identity 这 样 的 泛 型 函数 时 ， 编 译 器 要 求 你 在 函数 体 必须 正确 的 
使 用 这 个 通用 的 类 型 。 换 和 名 话说， 你 必须 把 这 些 和 参数 当做 是 任意 或 所 有 类 型 。 


看 下 之 前 identity 例子 : 


function identuty«I-(arg: T): T 4 
return arg; 


如 果 我 们 想 同 时 打印 出 arg 的 长 度 。 我 们 很 可 能 会 这 样 做 : 


function loggingIdentity<T>(arg: T): T ( 
console.log(arg.length); // Error: T doesn't have .length 
return arg; 





如 果 这 么 做 ， 编 译 器 会 报错 说 我 们 使 用 了 arg 的 .length 属性 ， 但 是 没有 地 方 
指明 arg 具有 这 个 属性 。 记 住 ， 这 些 类 型 变量 代表 的 是 任意 类 型 ， 所 以 使 用 这 个 
函数 的 人 可 能 传 入 的 是 个 数字 ， 而 数字 是 没有 .length 属性 的 。 


现在 假设 我 们 想 操作 T 类 型 的 数组 而 不 直接 是 T 。 由 于 我 们 操作 的 是 数组 ， 所 
以 .length 属性 是 应 该 存在 的 。 我 们 可 以 像 创建 其 它 数 组 一 样 创建 这 个 数组 : 


function loggingIdentity<T>(arg: T[]): T[] € 


console.log(arg.length);  // Array has a .length, so no more 
error 


return arg; 


你 可 以 这 样 理解 1oggingIdentity 的 类 型 : 24 HAR loggingIdentity ， 接 收 
类 型 参数 T 和 参数 arg ， 它 是 个 元 素 类 型 是 T 的 数组 ， 并 返回 元 素 类 型 

Æ T 的 数组 。 如 果 我 们 传 入 数字 数组 ， 将 返回 一 个 数字 数组 ， 因 为 此 时 or 的 的 
类 型 为 number 。 这 可 以 让 我 们 把 泛 型 变量 T 当 做 类 型 的 一 部 分 使 用 ， 而 不 是 整个 
类 型 ， 增 加 了 灵活 性 。 


我 们 也 可 以 这 样 实现 上 面 的 例子 


function loggingIdentity<T>(arg: Array<T>): Array<T> ( 
console.log(arg.length); // Array has a .length, so no more 
error 


return arg; 


使 用 过 其 它 语言 的 话 ， 你 可 能 对 这 种 语法 已 经 很 熟悉 了 。 在 下 一 节 ， 会 介绍 如 何 创 
建 自 定义 泛 型 像 Array<T> og o 


泛 型 类 型 


上 一 节 ， 我 们 创建 了 identity 通 用 函数， 可 以 适用 于 不 同 的 类 型 。 在 这 节 ， 我 们 研 
究 一 下 元 数 本 身 的 类 型 ， 以 及 如 何 创建 泛 型 接口 。 


泛 型 函数 的 类 型 与 非 泛 型 函数 的 类 型 没什么 不 同 ， 只 是 有 一 个 类 型 参数 在 最 前 面 ， 
eras 


function adentity<I>(arg: 1): T 4 
return arg; 


let myIdentity: <T>(arg: T) => T = identity; 


我 们 也 可 以 使 用 不 同 的 泛 型 参数 名 ， 只 要 在 数量 上 和 使 用 方式 上 能 对 应 上 就 可 以 。 


function identzty«er^(args T)* T 4 
return arg; 


let myIdentity: <U>(arg: U) => U = identity; 


我 们 还 可 以 使 用 带 有 调用 签名 的 对 象 字面 量 来 定义 泛 型 函数 ; 


Function identity<T>(arg: T): T { 
return arg; 


let myIdentity: {<T>(arg: T): T} = identity; 


这 引导 我 们 去 写 第 一 个 泛 型 接口 了 。 我 们 把 上 面 例子 里 的 对 象 字 面 


个 接口 : 


interface GenericIdentityFn { 
<T>(arg: T): T 


function identity<T>(arg: T): T { 
return arg; 


let myIdentity: GenericIdentityFn - identity; 


量 拿 出 来 做 为 一 


一 个 相似 的 例子 ， 我 们 可 能 想 把 泛 
清楚 的 知道 首 使 用 的 具体 是 哪个 泛 型 
这 样 接口 里 的 其 


Dictionary ) 


型 参数 当 作 整个 接口 的 一 个 参数 。 这 样 我 们 就 能 
类 型 t "TYVrU TUI 
它 


成 员 也 能 知道 这 个 参数 的 类 型 了 。 


interface GenericIdentityFn<T> { 


(arg: T): T 


fune croneident rey Tacande 
return arg; 


let myIdentity: GenericIdentityFn<number> = identity; 


ERB RNM RMT DARA RAWA BA mA h 


泛 型 类 型 一 部 分 
参数 来 指定 泛 型 类 型 (这 里 是 : number ) 


数 签名 作为 


当 我 们 使 用 GenericIdentityFn 的 时 候 ， 还 得 传 入 一 个 类 型 
， 锁定 了 之 后 代码 里 使 用 的 类 型 。 对 


于 描述 哪 部 分 类 型 属于 泛 型 部 分 来 说 ， 理 解 何 时 把 参数 放 在 调用 签名 里 和 何 时 放 在 
接口 上 是 很 有 帮助 的 。 


Hey 


除了 泛 型 接口 ， 我 们 还 可 以 创建 泛 型 类 。 注意 ， 无 法 创建 泛 型 枚 举 和 泛 型 命名 空 


泛 型 类 


泛 型 类 看 上 去 与 泛 型 接口 差不多 。 泛 型 类 使 用 ( <> ) 括 起 泛 型 类 型 ， 跟 在 类 名 
后 面 。 


class GenericNumber<T> { 
zeroValue: T; 
add: (x: T, y: T) => T; 


let myGenericNumber = new GenericNumber<number>(); 
myGenericNumber .zeroValue = 0; 
myGenericNumber.add = function(x, y) { return x + y; }; 


GenericNumber 类 的 使 用 是 十 分 直观 的 ， 并 且 你 可 能 已 经 注意 到 了 ， 没 有 什么 
限制 它 只 能 使 用 number 类 型 。 也 可 以 使 用 字符 串 或 其 它 更 复杂 M o 


let stringNumeric = new GenericNumber<string>(); 
stringNumeric.zeroValue = ""; 
stringNumeric.add = function(x, y) { return x + y; }; 


alert(stringNumeric.add(stringNumeric.zeroValue, "test")); 


与 接口 一 样 ， 直 接 把 泛 型 类 型 放 在 类 后 面 ， 可 以 帮助 我 们 确认 类 的 所 有 属性 都 在 使 
用 相同 的 类 型 。 


我 们 在 类 那 节 说 过 ， 类 有 两 部 分 : 静态 部 分 和 实例 部 分 。 泛 型 类 指 的 是 实例 部 分 的 
类 型 ， 所 以 类 的 静态 属性 不 能 使 用 这 个 泛 型 类 型 。 


乏 型 约束 


你 应 该 会 记得 之 前 的 一 个 例子 ， 我 们 有 时 候 想 操 作 某 类 型 的 一 组 值 ， 并 且 我 们 知道 
这 组 值 具有 什么 样 的 属性 。 在 loggingIdentity 例子 中 ， 我 们 想 访 

问 arg 的 length 属性 ， 但 是 编译 器 并 不 能 证 明 每 种 类 型 都 有 length 属性 ， 所 
以 就 报错 了 。 


function loggingIdentity<T>(arg: T): T { 
console.log(arg.length); // Error: T doesn't have .length 
return arg; 


相 比 于 操作 any 所 有 类 型 ， 我 们 想 要 限制 函数 去 处 理 任 意 带 有 length 属性 的 所 
有 类 型 。 只 要 传 入 的 类 型 有 这 个 属性 ， 我 们 就 允许 ， 就 是 说 至 少 包含 这 一 属性 。 

为 此 ， 我 们 需要 列 出 对 于 T 的 约束 要 求 。 

为 此 ， 我 们 定义 一 个 接口 来 描述 约束 条 件 。 创 建 一 个 包含 length 属性 的 接口 ， 
使 用 这 个 接口 和 extends 关键 字 来 实现 约束 : 


interface Lengthwise { 
length: number; 


function loggingIdentity«T extends Lengthwise>(arg: T): T ( 
console.log(arg.length); // Now we know it has a .length pr 
operty, so no more error 
return arg; 


现在 这 个 泛 型 函数 被 定义 了 约束 ， 因 此 它 不 再 是 适用 于 任意 类 型 : 


loggingIdentity(3); // Error, number doesn't have a .length pro 
perty 


我 们 需要 传 入 符合 约束 类 型 的 值 ， 必 须 包 含 必 须 的 属性 : 


loggingIdentity({length: 10, value: 3}); 


在 泛 型 约束 中 使 用 类 型 参数 


你 可 以 声明 一 个 类 型 参数 ， 且 它 被 另 一 个 类 型 参数 所 约束 。 比如 ， 现 在 我 们 想 要 用 
属性 名 从 对 象 里 获取 这 个 属性 。 并 且 我 们 想 要 确保 这 个 属性 存在 于 对 象 obj b> 
因此 我 们 需要 在 这 两 个 类 型 之 间 使 用 约束 。 


function getProperty<T, K extends keyof T>(obj: T, key: K) { 
return obj[key]; 


let x =f aa. p b: 2. Css So deca p. 
; // okay 


"a") 
getProperty(x, "m"); // error: Argument of type 'm' isn't assign 
able-to "a" | 5b^ | te” | 5d. 


getProperty(x, 


在 泛 型 里 使 用 类 类 型 
在 TypeScript 使 用 泛 型 创建 工厂 函数 时 ， 需 要 引用 构造 函数 的 类 类 型 。 比 如 ， 


function create<T>(c: {new(): T; }): T { 
return new c(); 


一 个 更 高 级 的 例子 ， 使 用 原型 属性 推断 并 约束 构造 函数 与 类 实例 的 关系 。 


class BeeKeeper { 
hasMask: boolean; 


class ZooKeeper { 
nametag: string; 


class Animal ( 
numLegs: number; 


class Bee extends Animal ( 
keeper: BeeKeeper; 


class Lion extends Animal { 
keeper: ZooKeeper; 


function createInstance<A extends Animal>(c: new () => A): 


return new c(); 


createInstance(Lion).keeper.nametag;  // typechecks! 
createInstance(Bee).keeper.hasMask; // typechecks! 


At 


TUR 


使 用 枚 举 我 们 可 以 定义 一 些 带 名 字 的 常量 。 使 用 枚 举 可 以 清晰 地 表达 意图 或 创建 一 
组 有 区 别 的 用 例 。 TypeScript 支 持 数 字 的 和 基于 字符 串 的 枚 举 。 


数字 枚 举 
首先 我 们 看 看 数字 枚 举 ， 如 果 你 使 用 过 其 它 编程 语言 应 该 会 很 熟悉 。 


enum Direction { 
Up = 45 
Down, 
Left, 
Right 


如 上 ， 我 们 定义 了 一 个 数字 枚 举 ， Up 使 用 初始 化 为 1 。 其 余 的 成 员 会 从 1 开 
始 自动 增长 。 换 和 句 话说 ， Direction.Up 的 值 
A 1* Down A 2 ° Left A 3 > Right W4 ° 


我 们 还 可 以 完全 不 使 用 初始 化 器 : 


enum Direction { 


Up, 
Down, 
Left, 
Right, 


现在 ， Up 594879 0 ， Down 的 值 为 1 等 等 。 当 我 们 不 在 乎 成 员 的 值 的 时 候 ， 
这 种 自 增长 的 行为 是 很 有 用 处 的 ， 但 是 要 注意 每 个 枚 举 成 员 的 值 都 是 不 同 的 。 


使 用 枚 举 很 简单 : 通过 枚 举 的 属性 来 访问 枚 举 成 员 ， 和 枚 举 的 名 字 来 访问 枚 举 类 
型 : 


enum Response { 
No = 0, 
Yes = 1, 


function respond(recipient: string, message: Response): void { 
7 


respond("Princess Caroline", Response.Yes) 


BF AT ARR A BY TT SE AS de E E (to P Pp) 。 简短 地 说 ， 不 带 初 始 化 
器 的 枚 举 或 者 被 放 在 第 一 的 位 置 ， 或 者 被 放 在 使 用 了 数字 常量 或 其 它 常 量 初始 化 了 
的 枚 举 后 面 。 换 名 话说， 下 面 的 情况 是 不 被 允许 的 : 


enum E { 
= getSomeValue(), 
B, // error! 'A' is not constant-initialized, so 'B' needs a 
n initializer 


j 


字符 串 枚 举 


字符 串 枚 举 的 概念 很 简单 ， 但 是 有 细微 的 运行 时 的 差别 。 在 一 个 字符 串 枚 举 里 ， 每 
个 成 员 都 必须 用 字符 串 字面 量 ， 或 另外 一 个 字符 串 枚 举 成 员 进行 初 始 化 。 


enum Direction { 
Up = se 
Down = "DOWN", 
Left = "LEFT", 
Right = "RIGHT", 


由 于 字符 串 枚 举 没 有 自 增长 的 行为 ， 字 符 串 枚 举 可 以 很 好 的 序列 化 。 换 句 话 说， 如 
果 你 正在 调试 并 且 必 须要 读 一 个 数字 枚 举 的 运行 时 的 值 ， 这 个 值 通常 是 很 难 读 的 - 
它 并 不 能 表达 有 用 的 信息 (尽管 反 向 映射 会 有 所 帮助 ) ， 字 符 串 枚 举 允许 你 提供 一 


个 运行 时 有 意义 的 并 且 可 读 的 值 ， 独 立 于 枚 举 成 员 的 名 字 。 


异 构 枚 举 — enums ) 


从 技术 的 角度 来 说 ， 枚 举 可 以 混合 字符 串 和 数字 成 员 ， 但 是 似乎 你 并 不 会 这 么 做 : 


enum BooleanLikeHeterogeneousEnum { 


No = 0, 
Yes = "YES", 


除非 你 真 的 想 要 利用 JavaScript 运 行 时 的 行为 ， 否 则 我 们 不 建议 这 样 做 。 


计算 的 和 常量 成 员 
每 个 枚 举 成 员 都 带 有 一 个 值 ， 它 可 以 是 常量 或 计算 出 来 的 。 HMR PAREN > 4 


举 成 员 被 当 作 是 常量 : 
它 是 枚 举 的 第 一 个 成 员 且 没有 初始 化 器 ， 这 种 情况 下 它 被 赋予 值 9 
W/E XS scons ant, 
enum E {X} 
e 它 不 带 有 初始 化 器 且 它 之 前 的 枚 举 成 员 是 一 个 数字 常量 。 这 种 情况 下 ， 当 前 枚 
举 成 员 的 值 为 它 上 一 个 枚 举 成 员 的 值 加 1。 


// All enum members in ' 
enum E1 { X, Y, Z} 


enum E2 { 
A BE 


e. 枚 举 成 员 使 用 常量 枚 举 表达 式 初始 化 。 常数 枚 举 表 达 式 是 TypeScript 表 达 式 的 
子 集 ， 它 可 以 在 编译 阶段 求 值 。 当 一 个 表达 式 满 足下 面条 件 之 一 时 ， 它 就 是 一 
个 常量 枚 举 表 达 式 : 


o 一 个 枚 举 表达 式 字 面 量 (主要 是 字符 串 字 面 量 或 数字 字面 量 ) 

o 一 个 对 之 前 定义 的 常量 枚 举 成 员 的 引用 (可 以 是 在 不 同 的 枚 举 类 型 中 定义 
的 ) 

o 带 括号 的 常量 枚 举 表 达 式 

o 一 元 运算 符 + ，- ，~ 其 中 之 一 应 用 在 了 常量 枚 举 表 达 式 

o 常量 枚 举 表达 式 做 为 二 元 运算 符 + ，- ，*,，/，,，%，<<，>>， 
>>>, &, |, ^ 的 操作 对 象 。 若 常数 枚 举 表达 式 求 值 后 
为 NaN 或 Infinity ， 则 会 在 编译 阶段 报错 。 


所 有 其 它 情况 的 枚 举 成 员 被 当 作 是 需要 计算 得 出 的 值 。 


enum FileAccess { 
// constant members 


None, 

Read =1 <<1, 

Write =1 << 2, 
Readwrite = Read | Write, 
// computed member 


G = "123".length 


联合 枚 举 与 枚 举 成 员 的 类 型 
存在 一 种 特殊 的 非 计算 的 常量 枚 举 成 员 的 子 集 : 字面 量 枚 举 成 员 。 字 面 量 枚 举 成 员 
是 指 不 带 有 初始 值 的 常量 枚 举 成 员 ， 或 者 是 值 被 初始 化 为 


e 任何 字符 串 字 面 量 (例如 : "foo" ， "bar" > "baz" ) 
e 任何 数字 字面 量 (例如 : 1, 100 ) 
e 应 用 了 一 元 - 符号 的 数字 字面 量 (Pl: -1, -100 ) 


当 所 有 枚 举 成 员 都 拥有 字面 量 枚 举 值 时 ， 它 就 带 有 了 一 种 特殊 的 语义 。 
首先 ， 枚 举 成 员 成 为 了 类 型 ! 例如 ， 我 们 可 以 说 某 些 成 员 只 能 是 枚 举 成 员 的 值 : 


enum ShapeKind { 
Circle, 
Square, 


interface Circle { 
kind: ShapeKind.Circle; 
radius: number; 


interface Square { 
kind: ShapeKind. Square; 
sideLength: number; 


leer Circle et 
kind: ShapeKind.Square, 
Tike S E Error! 
radius: 100, 


另 一 个 变化 是 枚 举 类 型 本 身 变 成 了 每 个 枚 举 成 员 的 联合 。 虽然 我 们 还 没有 讨论 联合 
类 型 ， 但 你 只 要 知道 通过 联合 枚 举 ， 类 型 系统 能 够 利用 这 样 一 个 事实 ， 它 可 以 知道 
枚 举 里 的 值 的 集合 。 因此，TypeScript 能 够 捕获 在 比较 值 的 时 候 犯 的 轧 屯 的 错误 。 
例如 : 


enum E { 
Foo, 
Bar, 
j 


FUNGEL E(x. Ey St 


if (x !== E.Foo || x !== E.Bar) { 
Ng ee 
// Error! Operator '!==' cannot be applied to types 'E.F 


oo' and 'E.Bar'. 


j 


这 个 例子 里 ， 我 们 先 检查 x 是 否 不 是 E.Foo 。 如 果 通 过 了 这 个 检查 ， 然 
后 || 会 发 生 短 路 效果 ， if 语句 体 里 的 内 容 会 被 执行 。 然 而， 这 个 检查 没有 通 
To MZA x 则 只 能 为 E.Foo ， 因 此 没 理 由 再 去 检查 它 是 否 为 E.Bar © 


运行 时 的 枚 举 


枚 举 是 在 运行 时 丨 正 存 在 的 对 象 。 例 如 下 面 的 枚 举 : 


WwW 


can actually be passed around to functions 


functron ob): f X: number H) f 
return obj.X; 


1 





// Works, Since 'E' has a property named 'X' which is a number. 


f(E); 


反 向 映射 


除了 创建 一 个 以 属性 名 做 为 对 象 成 员 的 对 象 之 外 ， 数 字 枚 举 成 员 还 具有 了 反 向 映 
射 ， 从 枚 举 值 到 枚 举 名 字 。 例 如 ， 在 下 面 的 例子 中 : 


enum Enum { 
A 


} 


let a = Enum.A; 
let nameOfA = Enum[a]; // "A" 


TypeScript 可 能 会 将 这 段 代码 编译 为 下 面 的 JavaScript : 


var Enum; 

(function (Enum) { 
Enum[Enum["A"] = 0] = "A"; 

j)(Enum || (Enum = {})); 


var a = Enum.A; 
var nameOfA = Enum[a]; // "A" 


生成 的 代码 中 ， 枚 举 类 型 被 编译 成 一 个 对 象 ， 它 包含 了 正 向 映射 ( name -> 
value ) 和 反 向 映射 ( value -> name ) 。 引 用 枚 举 成 员 总 会 生成 为 对 属性 
访问 并 且 永 远 也 不 会 内 联 代 码 。 


要 注意 的 是 不 会 为 字符 囊 枚 举 成 员 生 成 反 向 映射 。 


const 枚 举 


大 多 数 情况 下 ， 枚 举 是 十 分 有 效 的 方案 。 然而 在 某 些 情况 下 需求 很 严格 。 为 了 避 
免 在 额 i i 外 的 非 直 接 的 对 枚 举 成 员 的 访问 ， 我 们 可 以 使 
用 const 枚 举 。 常 量 枚 举 通 过 在 枚 举 上 使 用 const 修饰 符 来 定义 。 


const enum Enum { 
A= 1, 
B=A* 2 


Ww 


常量 枚 举 只 能 使 用 常量 枚 举 表 达 式 ， 并 且 不 同 于 常规 的 枚 举 ， 它 们 在 编译 阶段 会 
删除 。 常量 枚 举 成 员 在 使 用 的 地 方 会 被 内 联 进 来 。 之 所 以 可 以 这 么 做 是 因为 ， 


const enum Directions { 


Up, 

Down, 
Left, 
Right 


let directions = [Directions.Up, Directions.Down, Directions.Lef 
t, Directions.Right ] 


生成 后 的 代码 为 : 


Var directions = [0 7* Up. “7, «/* Down 7.2 47 lefe “7,7 37 Rk 
towe S/s 


外 部 枚 举 
外 部 枚 举 用 来 描述 已 经 存在 的 枚 举 类 型 的 形状 。 


declare enum Enum { 


poco 
B, 
(rum 


外 部 枚 举 和 非 外 部 枚 举 之 间 有 一 个 重要 的 区 别 ， 在 正常 的 枚 举 里 ， 没 有 初始 化 方法 
的 成 员 被 当成 常数 成 员 。 对 于 非常 数 的 外 部 枚 举 而 言 ， 没 有 初始 化 方法 时 被 当做 需 
要 经 过 计算 的 。 


这 节 介 绍 TypeScript 里 的 类 型 推论 。 即 ， 类 型 是 在 哪里 如 何 被 推断 的 。 


基础 


TypeScript 里 ， 在 有 些 没 有 明确 指出 类 型 的 地 方 ， 类 型 推论 会 帮助 提供 类 型 。 如 下 
面 的 例子 


let x = 3; 


变量 x 的 类 型 被 推断 为 数字 。 这 种 推断 发 生 在 初始 化 变量 和 成 员 ， 设 置 默认 参数 
值 和 决定 函数 返回 值 时 。 


大 多 数 情况 下 ， 类 型 推论 是 直 堆 了 当地。 后面 ， 我 们 会 浏览 类 型 推论 时 的 细 
微 差别 。 


也 佳 通用 类 型 


T ea en 型 时 候 ， 会 使 用 这 些 表达 式 的 类 型 来 推断 出 一 个 最 合 
适 的 通用 类 型 。 例 如 ， 


let x = [0, 1, null]; 


为 了 推断 x 的 类 型 ， 我 们 必须 考虑 所 有 元 素 的 类 型 。 这 里 有 两 种 选 
择 : number 和 null 。 计算 通用 类 型 算法 会 考虑 所 有 的 候选 类 型 ， 并 给 
兼容 所 有 候选 类 型 的 类 型 。 


由 于 最 终 的 通用 类 型 取 自 候选 


类 型 ， 有 些 时候 候 选 类 型 共享 相同 的 通用 类 型 ， 但 是 
却 没 有 一 个 类 型 能 做 为 所 有 候选 


型 ， 有 些 
类 型 的 类 型 。 例 如 : 


let zoo = [new Rhino(), new Elephant(), new Snake()]; 


这 里 ， 我 们 想 让 zoo 被 推断 为 Animal[] 类 型 ， 但 是 这 个 数组 里 没有 对 象 
是 Animal 类 型 的 ， 因 此 不 能 推断 出 这 个 结果 。 为 了 更 正 ， 当 候选 类 型 不 能 使 用 
的 时 候 我 们 需要 明确 的 指出 类 型 : 


let zoo: Animal[] = [new Rhino(), new Elephant(), new Snake()]; 


如 果 没 有 找到 最 佳 通用 类 型 的 话 ， 类 型 推断 的 结果 为 联合 数组 类 型 (Rhino | 
Elephant | Snake)[] ° 


上 下 文 类 型 


TypeScript 类 型 推论 也 可 能 按照 相反 的 方向 进行 。 这 被 叫做 “ 按 上 下 文 归 类 ”。 按 上 
下 文 归 类 会 发 生 在 表达 式 的 类 型 与 所 处 的 位 置 相关 时 。 比 如 : 


window.onmousedown = function(mouseEvent) { 
console.log(mouseEvent.button); //<- Error 


Po 


这 个 例子 会 得 到 一 个 类 型 错误 ，TypeScript 类 型 检查 器 使 

用 window.onmousedown 函数 的 类 型 来 推断 右边 函数 表达 式 的 类 型 。 因此， 就 能 
推断 出 mouseEvent 参数 的 类 型 了 。 如果 函数 表达 式 不 是 在 上 下 文 类 型 的 位 

置 ， mouseEvent 参数 的 类 型 需要 指定 为 any ， 这 样 也 不 会 报错 了 。 


如 果 上 下 文 类 型 表达 式 包 含 了 明确 的 类 型 信息 ， 上 下 文 的 类 型 被 忽略 。 重 写 上 面 的 
例子 : 


window.onmousedown = function(mouseEvent: any) { 
console.log(mouseEvent.button); //<- Now, no error is given 


}; 


这 个 函数 表达 式 有 明确 的 参数 类 型 注解 ， 上 下 文 类 型 被 忽略 。 这 样 的 话 就 不 报错 
了 ， 因 为 这 里 不 会 使 用 到 上 下 文 类 型 。 


上 下 文 归 类 会 在 很 多 情况 下 使 用 到 。 通常 包含 函数 的 参数 ， 赋 值 表 达 式 的 右边 ， 类 
型 断言 ， 对 象 成 员 和 数组 字面 量 和 返回 值 语 句 。 上 下 文 类 型 也 会 做 为 最 佳 通用 类 型 
的 候选 类 型 。 比 如 : 


function createZoo(): Animal[] { 
return [new Rhino(), new Elephant(), new Snake()]; 


这 个 例子 里 ， 最 佳 通 用 类 型 有 4 个 候选 
者 : Animal ， Rhino ， Elephant 和 Snake ° 当然 ， Animal 会 被 做 为 最 
佳 通 用 类 型 。 


TypeScript 里 的 类 型 兼容 性 是 基于 结构 子 类 型 的 。 结构 类 型 是 一 种 只 使 用 其 成 员 来 
描述 类 型 的 方式 。 它 正 好 与 名 义 (nominal) 类 型 形成 对 比 。 (HE: 在 基于 名 
义 类 型 的 类 型 系统 中 ， 数 据 类 型 的 兼容 性 或 等 价 性 是 通过 明确 的 声明 和 /或 类 型 的 名 
称 来 决定 的 。 这 与 结构 性 类 型 系统 不 同 ， 它 是 基于 类 型 的 组 成 结构 ， 且 不 要 求 明确 
地 声明 。) 看 下 面 的 例子 : 


interface Named { 
name: string; 


class Person { 
name: string; 


let p: Named; 


= 


// OK, because of structural typing 


p = new Person(); 


在 使 用 基于 名 义 类 型 的 语言 ， 比 如 C# 或 Java 中 ， 这 段 代码 会 报错 ， 因 为 Person 类 
没有 明确 说 明 其 实现 了 Named 接 口 。 


TypeScript 的 结构 性 子 类 型 是 根据 JavaScript 代 码 的 典型 写法 来 设计 的 。 因为 
JavaScript 里 广泛 地 使 用 匿名 对 象 ， 例 如 函数 表达 式 和 对 象 字 面 量 ， 所 以 使 用 结构 
类 型 系统 来 描述 这 些 类 型 比 使 用 名 义 类 型 系统 更 好 。 


关于 可 靠 性 的 注意 事项 


TypeScript 的 类 型 系统 允许 某 些 在 编译 阶段 无 法 确认 其 安全 性 的 操作 。 当 一 个 类 型 
系统 具 此 属性 时 ， 被 当做 是 “不 可 靠 ” 的 。TypeScript 允 许 这 种 不 可 靠 行为 的 发 生 是 经 
过 仔细 考虑 的 。 通 过 这 篇 文章 ， 我 们 会 解释 什么 时 候 会 发 生 这 种 情况 和 其 有 利 的 一 
os 


开始 


TypeScript 结 构 化 类 型 系统 的 基本 规则 是 ， 如 果 x 要 兼容 y PA y 至 少 具 有 
与 x 相同 的 属性 。 比 如 : 


interface Named { 
name: string; 


let x: Named; 
// y's inferred type is { name: string; location: string; } 
let y = { name: 'Alice', location: 'Seattle' }; 


x = y, 


这 里 要 检查 y 是 否 能 赋值 给 x ， 编 译 器 检查 x 中 的 每 个 属性 ， 看 是 否 能 
在 y 中 也 找到 对 应 属性 。 在 这 个 例子 中 ， y 必须 包含 名 字 
Æ name 的 string 类 型 成 员 。 y 满足 条 件 ， 因 此 赋值 正确 。 


检查 函数 参数 时 使 用 相同 的 规则 : 


function greet(n: Named) { 
alert('Hello, ' + n.name); 


} 
greet(y); // OK 


注意 ，y 有 个 额外 的 location 属性 ， 但 这 不 会 引发 错误 。 只 有 目标 类 型 (这 里 
是 Named ) 的 成 员 会 被 一 一 检查 是 否 兼容 。 


这 个 比较 过 程 是 递归 进行 的 ， 检 查 每 个 成 员 及 子 成 员 。 
比较 两 个 函数 
相对 来 讲 ， 在 比较 原始 类 型 和 对 象 类 型 的 时 候 是 比较 容易 理解 的 ， 问 题 是 如 何 判断 


两 个 防 数 是 兼容 的 。 下 面 我 们 从 两 个 简单 的 函数 入 手 ， 它 们 仅 是 参数 列表 略 有 不 
同 : 


let x = (a: number) => 0; 
(b: number, s: string) => 0; 


[Ex 

(D 

E 
Il 


y = x; // OK 
x = y; Error 


要 查看 x 是 否 能 赋值 给 y ， 首 先 看 它们 的 参数 列表 。 x 的 每 个 参数 必须 能 
在 y 里 找到 对 应 类 型 的 参数 。 注意 的 是 参数 的 名 字 相 同 与 否 无 所 谓 ， 只 看 它们 的 
类 型 。 这 里 ，x 的 每 个 参数 在 y 中 都 能 找到 对 应 的 参数 ， 所 以 允许 赋值 。 


二 个 赋值 错误 ， 因 为 y 有 个 必需 的 第 二 个 参数 ， 但 是 x 并 没有 ， 所 以 不 允许 赋 
你 可 能 会 疑惑 为 什么 允许 忽略 参数 ， 像 例子 y = x 中 那样 。 原 因 是 忽略 额外 的 
参数 在 JavaScript 里 是 很 常见 的 。 例如， Array#forEach 给 回调 函数 传 3 个 参 


数 : 数组 元 素 ， 索 引 和 整个 数组 。 尽管 如 此 ， 传 入 一 个 只 使 用 第 一 个 参数 的 回调 函 
数 也 是 很 有 用 的 : 


let items = [1, 2, 3]; 


// Don't force these extra arguments 
items.forEach((item, index, array) => console.log(item)); 


// Should be OK! 
items.forEach((item) => console.log(item)); 


下 面 来 看 看 如 何 处 理 返 回 值 类 型 ， 创 建 两 个 仅 是 返回 值 类 型 不 同 的 函数 : 


let x = () => ((name: 'Alice'}); 
let y () => ({name: 'Alice', location: 'Seattle'}); 


y; // OK 
y = x; // Error because x() lacks a location property 
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赋值 成 功 。 这 是 不 稳定 的 ， 因 为 调用 者 可 能 传 入 了 一 个 具有 更 精确 类 型 信息 的 函 
数 ， 但 是 调用 这 个 传 入 的 函数 的 时 候 却 使 用 了 不 是 那么 精确 的 类 型 信息 。 实 际 上 ， 
这 极 少 会 发 生 错误 ， 并 且 能 够 实现 很 多 JavaScript 里 的 常见 模式 。 例 如 : 


enum EventType { Mouse, Keyboard } 


interface Event { timestamp: number; } 
interface MouseEvent extends Event { x: number; y: number } 
interface KeyEvent extends Event { keyCode: number } 


function listenEvent(eventType: EventType, handler: (n: Event) = 
> void) { 
CA 


// Unsound，but useful and common 
listenEvent(EventType.Mouse, (e: MouseEvent) => console.log(e.x 


3o sep 


// Undesirable alternatives in presence of soundness 
listenEvent(EventType.Mouse, (e: Event) -» console.log((«MouseEv 
ent>e).x + ',' + (<MouseEvent>e).y)); 
listenEvent(EventType.Mouse, <(e: Event) => void>((e: MouseEvent 
) => console.log(e.x + ',' + e.y))); 


// Still disallowed (clear error). Type safety enforced for whol 
ly incompatible types 
listenEvent(EventType.Mouse, (e: number) => console.log(e)); 


可 选 参数 及 剩余 参数 


比较 函数 兼容 性 的 时 候 ， 可 选 参数 与 必须 参数 是 可 互 换 的 。 源 类 型 上 有 额外 的 可 选 
参数 不 是 错误 ， 目 标 类 型 的 可 选 参数 在 源 类 型 里 没有 对 应 的 参数 也 不 是 错误 。 


当 一 个 函数 有 剩余 参数 时 ， 它 被 当做 无 限 个 可 选 参数 。 


这 对 于 类 型 系统 来 说 是 不 稳定 的 ， 但 从 运行 时 的 角度 来 看 ， 可 选 参数 一 般 来 说 是 不 
强制 的 ， 因 为 对 于 大 多 数 函 数 来 说 相当 于 传递 了 一 些 undefinded ° 


有 一 个 好 的 例子 ， 常 见 的 隐 数 接收 一 个 回调 部 数 并 用 对 于 程序 员 来 说 是 可 预知 的 参 
数 但 对 类 型 系统 来 说 是 不 确定 的 参数 来 调用 : 


function invokeLater(args: any[], callback: (...args: any[]) => 
void) { 
/* ... Invoke callback with 'args' ... */ 


// Unsound - invokeLater "might" provide any number of arguments 
invokeLater([1, 2], (x, y) => console.log(x + ', ' + y)); 


// Confusing (x and y are actually required) and undiscoverable 
invokeLater([1, 2], (x?, y?) => console.log(x + ', ' + y)); 


对 于 有 重 载 的 函数 ， 源 函数 的 每 个 重 载 都 要 在 目标 函数 上 找到 对 应 的 函数 签名 。 这 


确保 了 目标 函数 可 以 在 所 有 源 函 数 可 调用 的 地 方 调用 。 


TUR 


枚 举 类 型 与 数字 类 型 兼容 ， 并 且 数 字 类 型 与 枚 举 类 型 兼容 。 不 同 枚 举 类 型 之 间 是 不 
兼容 的 。 比 如 ， 


enum Status { Ready, Waiting }; 
enum Color { Red, Blue, Green }; 


let status = Status.Ready; 
status = Color.Green; //error 


类 与 对 象 字 面 量 和 接口 差 ， 但 有 一 点 不 同 : 类 有 静态 部 分 和 实例 部 分 的 类 型 。 
比较 两 个 类 类 型 es , pesos 会 被 比较 6 i 态 成 员 和 构造 函数 不 在 比 
较 的 范围 内 。 


class Animal { 
feet: number; 
constructor(name: string, numFeet: number) { } 


class Size t 
feet: number; 
constructor(numFeet: number) ( ) 


let a: Animal; 
let s: Size; 


类 的 私有 成 员 和 受 保 护 成 员 


类 的 私有 成 员 和 受 保护 成 员 会 影响 兼容 性 。 当 检 查 类 实例 的 兼容 时 ， 如 果 目 标 类 型 

包含 一 个 私有 成 员 ， 那 么 源 类 型 必须 包含 来 自 同 一 个 类 的 这 个 私有 成 员 。 同样 地 ， 

这 条 规则 也 适用 于 包含 受 保护 成 员 实 例 的 类 型 检查 。 这 允许 子 类 赋值 给 父 类 ， 但 是 
不 能 赋值 给 其 它 有 同样 类 型 的 类 。 


泛 型 


因为 TypeScript 是 结构 性 的 类 型 系统 ， 类 型 参数 只 影响 使 用 其 做 为 类 型 一 部 分 的 结 
果 类 型 。 比 如 ， 


interface Empty<T> { 
j 


let x: Empty<number>; 
let y: Empty<string>; 


x= y; // okay, y matches structure of x 


上 面 代码 里 ，x 和 y 是 兼容 的 ， 因 为 它们 的 结构 使 用 类 型 参数 时 并 没有 什么 不 
A o 把 这 个 例子 改变 一 下 ， 增 加 一 个 成 员 ， 就 能 看 出 是 如 何 工 作 的 了 : 


interface NotEmpty<T> { 
data: T; 
j 


let x: NotEmpty<number>; 
let y: NotEmpty<string>; 


x= y; // error, x and y are not compatible 


这 里 ， 泛 型 类 型 在 使 用 时 就 好 比 不 是 一 个 泛 型 类 型 。 


这 
对 于 没 指 定 泛 型 类 型 的 泛 型 参数 时 ， 会 把 所 有 泛 型 参数 当成 any 比较 。 然后 用 结 
果 类 型 进行 比较 ， 就 像 上 面 第 一 个 例子 。 


上 比如， 


let identity = function<T>(x: T): T { 
CA 


let reverse = function<U>(y: U): U ( 
Vihear: 


identity = reverse; // Okay because (x: any)=>any matches (y: a 
ny )=>any 


子 类 型 与 赋值 


目前 为 止 ， 我 们 使 用 了 “兼容 性 ”， 它 在 语言 规范 里 没有 定义 。 在 TypeScript 里 ， 有 
两 种 兼容 性 : 子 类 型 和 赋值 。 它 们 的 不 同 点 在 于 ， 赋 值 扩展 了 子 类 型 兼容 性 ， 增 加 
了 一 些 规 则 ， 允 许 和 any 来 回 赋值 ， 以 及 enum 和 对 应 数字 值 之 间 的 来 回 赋值 。 


语言 里 的 不 同 地 方 分 别 使 用 了 它们 之 中 的 机 制 。 实际 上 ， 类 型 兼容 性 是 由 赋值 兼容 
性 来 控制 的 ， 即 使 在 implements 和 extends 语句 也 不 例外 。 


更 多 信息 ， 请 参阅 TypeScript 语 言 规范 . 


交叉 类 型 (Intersection Types) 


交叉 类 型 是 将 多 个 类 型 含 并 为 一 个 类 型 。 这 让 我 们 可 以 把 现 有 的 多 种 类 型 过 加 到 一 
起 成 为 一 种 类 型 ， 它 包含 了 所 需 的 所 有 类 型 的 特性 。 例 如 ， Person & 
Serializable & Loggable 同时 是 Person 和 Serializable 和 Loggable 。 
就 是 说 这 个 类 型 的 对 象 同时 拥有 了 这 三 种 类 型 的 成 员 。 

我 们 大 多 是 在 混入 (mixins) 或 其 它 不 适合 典型 面向 对 象 模型 的 地 方 看 到 交叉 类 型 
的 使 用 。 (在 JavaScript 里 发 生 这 种 情况 的 场合 很 多 1 ) 下 面 是 如 何 创建 混入 的 一 
个 简单 例子 ("target": "es5") : 


function extend<T, U>(first: T, second: U): T&U { 
let result = <T & U>{}; 
for (let 1d in first) 4 
(<any>result)[id] = (<any>first)[id]; 
} 
for (let id in second) { 
if (!result.hasOwnProperty(id)) { 
(<any>result)[id] = (<any>second) [id]; 


} 


return result; 


class Person { 

constructor (public name: string) { } 
} 
interface Loggable { 

log(): void; 


} 
class ConsoleLogger implements Loggable { 
log() { 
M 
} 
} 


var jim = extend(new Person("Jim"), new ConsoleLogger()); 
var n = jim.name; 
jim.log(); 


联合 类 型 (Union Types) 


联合 类 型 与 交叉 类 型 很 有 关联 ， 但 是 使 用 上 却 完 全 不 同 。 偶尔 你 会 遇 到 这 种 情况 ， 
一 个 代码 库 硕 望 传 入 number 或 string 类 型 的 参数 。 例 如 下 面 的 函数 : 


/** 
* Takes a string and adds "padding" to the left. 
* If 'padding' is a string, then 'padding' is appended to the 1 
eft side. 
* If 'padding' is a number, then that number of spaces is added 
to the left side. 


p 
function padLeft(value: string, padding: any) { 
if (typeof padding === "number") { 
return Array(padding + 1).join(" ") + value; 
} 
if (typeof padding === "string") { 
return padding + value; 
J 
throw new Error( Expected string or number, got '${padding}' 
0); 
} 
padLeft("Hello world", 4); // returns " Hello world" 


padLeft 存在 一 个 问题 ， padding 参数 的 类 型 指定 成 了 any 。 这 就 是 说 我 们 
可 以 传 入 一 个 既 不 是 number 也 不 是 string 类 型 的 参数 ， 但 是 TypeScript 却 不 报 


错 。 


let indentedString = padLeft("Hello world", true); // 编译 阶段 通过 
> 运行 时 报错 


在 传统 的 面向 对 象 语 言 里 ， 我 们 可 能 会 将 这 两 种 类 型 抽象 成 有 层级 的 类 型 。 BAK 
显然 是 非常 清晰 的 ， 但 同时 也 存在 了 过 度 设 计 。 padLeft 原始 版 本 的 好 处 之 一 是 
允许 我 们 传 入 原始 类 型 。 这 样 做 的 话 使 用 起 来 既 简 单 又 方便 。 如 果 我 们 就 是 想 使 
用 已 经 存在 的 子 数 的 话 ， 这 种 新 的 方式 就 不 适用 了 。 


代替 any ， 我 们 可 以 使 用 联合 类 型 做 为 padding 的 参数 : 


[Pe 

* Takes a string and adds "padding" to the left. 

* If 'padding' is a string, then 'padding' is appended to the 1 
eft side. 


* If 'padding' is a number, then that number of spaces is added 
to the left side. 
i 
function padLeft(value: string, padding: string | number) { 
JP ERE 


let indentedString - padLeft("Hello world", true); // errors dur 
ing compilation 


联合 类 型 表示 一 个 值 可 以 是 几 种 类 型 之 一 。 我 们 用 坚 线 ( | ) 分 隔 每 个 类 型 ， 所 
vA number | string | boolean 表示 一 个 值 可 以 是 number ， string ， 
或 boolean 。 


如 果 一 个 值 是 联合 类 型 ， 我 们 只 能 访问 此 联合 类 型 的 所 有 类 型 里 共有 的 成 员 。 


interface Bird { 


fly(); 
layEggs(); 


interface Fish { 
swim(); 
layEggs(); 


function getSmallPet(): Fish | Bird { 
Lf os 


let pet - getSmallPet(); 
pet.layEggs(); // okay 
pet.swim(); // errors 


里 的 联合 类 型 可 能 有 点 复杂 ， 但 是 你 很 容易 就 习惯 了 。 如 果 一 个 值 的 类 型 是 A 
B ， 我 们 能 够 确定 的 是 它 包含 了 A 和 B 中 共有 的 成 员 。 这 个 例子 

， Bird 具有 一 个 fly 成 员 。 我 们 不 能 确定 一 个 Bird | Fish 类 型 的 变量 是 
有 fly 方法 。 如 果 变 量 在 运行 时 是 Fish 类 型 ， 那 么 调用 pet.fly() 就 出 错 


zx 
| 

里 
个 
了 


类 型 保护 与 区 分 类 型 (Type Guards and 
Differentiating Types ) 
联合 类 型 适合 于 那些 值 可 以 为 不 同类 型 的 情况 。 但 当 我 们 想 确切 地 了 解 


为 Fish 时 怎么 办 ? JavaScript 里 常用 来 区 分 2 个 可 能 值 的 方法 是 检查 成 员 是 否 存 
在 。 如 之 前 提 及 的 ， 我 们 只 能 访问 联合 类 型 中 共同 拥有 的 成 员 。 


€ 


eu 


let pet - getSmallPet(); 


if (pet.swim) ( 
pet.swim(); 


} 

else if (pet.fly) { 
pet.fly(); 

} 


为 了 让 这 段 代码 工作 ， 我 们 要 使 用 类 型 断言 : 


let pet = getSmallPet(); 


if ((<Fish>pet).swim) { 
(«Fish»pet).swim(); 


} 

else { 
(<Bird>pet).fly(); 

} 


用 户 目 定义 的 类 型 保护 


这 里 可 以 注意 到 我 们 不 得 不 多 次 使 用 类 型 断言 。 假 若 我 们 一 旦 检查 过 类 型 ， 就 能 在 
之 后 的 每 个 分 支 里 清楚 地 知道 pet 的 类 型 的 话 就 好 了 o 


TypeScript 里 的 类 型 保护 机 制 让 它 成 为 了 现实 。 类 型 保护 就 是 一 些 表 达 式 ， 它 们 会 
在 运行 时 检查 以 确保 在 某 个 作用 域 里 的 类 型 。 要 定义 一 个 类 型 保护 ， 我 们 只 要 简单 
地 定义 一 个 函数 ， 它 的 返回 值 是 一 个 类 型 谓词 : 


FUNETION nsersh(pet kBish | Bird): pet is Fish 


return (<Fish>pet).swim !== undefined; 


在 这 个 例子 里 ， pet is Fish 就 是 类 型 谓词 。 谓 词 为 parameterName is 
Type 这 种 形式 ， parameterName 必须 是 来 自 于 当前 函数 签名 里 的 一 个 参数 名 。 


一 些 变量 调用 isFish 时 ，TypeScript 会 将 变量 缩减 为 那个 具体 的 类 型 ， 
只 个 类 型 与 变量 的 原始 类 型 是 兼容 的 。 
// ‘Swim 1 lly Yel J| AR x 问题 了 


if (isFish(pet)) { 
pet.swim(); 


j 

else ( 
pet.fly(); 

j 


注意 TypeScript 不 仅 知 道 在 if 4-3 € pet 是 Fish 类 型 ; 它 还 清楚 在 else 分 
支 里 ， 一 定 不 是 Fish 类 型 ， 一 定 是 Bird 类 型 。 


typeof 类 型 保护 


现在 我 们 回 过 头 来 看 看 怎么 使 用 联合 类 型 书写 padLeft 代码 。 我 们 可 以 像 下 面 这 
样 利 用 类 型 断言 来 写 


function isNumber(x: any): x is number { 
return typeof x --- "number"; 


function isString(x: any): x is string ( 
return typeof x === "string"; 


function padLeft(value: string, padding: string | number) ( 
if (isNumber(padding)) { 
return Array(padding + 1).join(" ") + value; 
} 
if (isString(padding)) { 
return padding + value; 
} 
throw new Error( Expected string or number, got '${padding}' 


0); 


然而 ， 必 须要 定义 一 个 函数 来 判断 类 型 是 否 是 原始 类 型 ， 这 太 痛 将 了 。 幸运 的 是 ， 
现在 我 们 不 必 将 typeof x === "number" 抽象 成 一 个 函数 ， 因 为 TypeScript 可 以 
将 它 识 别 为 一 个 类 型 保护 。 也 就 是 说 我 们 可 以 直接 在 代码 里 检查 类 型 了 。 


function padLeft(value: string, padding: string | number) { 
if (typeof padding === "number") { 
return Array(padding + 1).join(" ") + value; 


} 

if (typeof padding === "string") { 
return padding + value; 

} 


throw new Error( Expected string or number, got '${padding}' 


0): 


j 
这 些 typeof 类 型 保护 只 有 两 种 形式 能 被 识别 : typeof v === 
"typename" 和 typeof v !-- "typename" > "typename" 必须 


日 


是 "number" * "string" * "boolean" 或 "symbol" ° 但 是 TypeScript 并 不 
会 阻止 你 与 其 它 字符 串 比 较 ， 语 言 不 会 把 那些 表达 式 识别 为 类 型 保护 。 


instanceof 类 型 保护 
如 果 你 已 经 阅读 了 typeof 类 型 保护 并 且 对 JavaScript 里 的 instanceof 操作 符 熟 
悉 的 话 ， 你 可 能 已 经 猜 到 了 这 节 要 讲 的 内 容 。 


instanceof 类 型 保护 是 通过 构造 函数 来 细 化 类 型 的 一 种 方式 。 比如 ， 我 们 借鉴 
一 下 之 前 字符 串 填 充 的 例子 : 


interface Padder { 
getPaddingString(): string 


class SpaceRepeatingPadder implements Padder { 
constructor(private numSpaces: number) { } 
getPaddingString() { 
return Array(this.numSpaces + 1).join(" "); 


class StringPadder implements Padder { 
constructor(private value: string) { } 
getPaddingString() { 
return this.value; 


function getRandomPadder() { 
return Math.random() < 0.5 ? 
new SpaceRepeatingPadder (4) 
new StringPadder("  "); 


// XÆ 7 SpaceRepeatingPadder | StringPadder 
let padder: Padder - getRandomPadder(); 


if (padder instanceof SpaceRepeatingPadder) { 
padder; // 类 型 细 化 为 'SpaceRepeatingPadder' 


} 
if (padder instanceof StringPadder) { 


padder; // 类 型 细 化 为 'StringPadder' 


instanceof 的 右 侧 要 求 是 一 个 构造 函数 ，TypeScript 将 细 化 为 : 


1. 此 构造 函数 的 prototype 属性 的 类 型 ， 如 果 它 的 类 型 不 为 any 的 话 
2. 构造 签名 所 返回 的 类 型 的 联合 


以 此 顺序 。 


可 以 为 null 的 类 型 


TypeScript 具 有 两 种 特殊 的 类 型 ， null 和 undefined ， 它 们 分 别 具 有 值 null 和 
undefined. 我 们 在 基础 类 型 一 节 里 已 经 做 过 简要 说 明 。 默认 情况 下 ， 类 型 检查 器 认 
为 null 与 undefined 可 以 赋值 给 任何 类 型 。 null 5 undefined 是 所 有 其 
它 类 型 的 一 个 有 效 值 。 这 也 意味 着 ， 你 阻止 不 了 将 它们 赋值 给 其 它 类 型 ， 就 算是 你 
想 要 阻止 这 种 情况 也 不 行 。 null 的 发 明 者 ，Tony Hoare， 称 它 为 价值 亿 万 美金 


的 错误 。 


--strictNullChecks 标记 可 以 解决 此 错误 : 当 你 声明 一 个 变量 时 ， 它 不 会 自动 
地 包含 null 或 undefined ° 你 可 以 使 用 联合 类 型 明确 的 包含 它们 : 


ler $ = nOD 

s = null; // 错误 ， 'nul1' 不 能 赋值 给 'string' 
let sh: string | null = "bar"; 

Si null: 77 s 


I 


sn = undefined; // error, ‘undefined! 7AE RIEA 'string | null' 
注意 ， 按 照 JavaScript 的 语义 ，TypeScript 会 把 null fe undefined 区 别 对 待 。 


string | null > string | undefined 和 string | undefined | null X 
不 同 的 类 型 。 


可 选 参 数 和 可 选 属性 


使 用 了 --strictNullChecks ， 可 选 参数 会 被 自动 地 加 上 | undefined : 


function f(x: number, y?: number) { 
return x + (y || 0); 
} 
NO2) 
f(1); 
f(1, undefined); 
h(a null); // error, ‘null as not assignable ta 
fined' 


可 选 属性 也 会 有 同样 的 处 理 : 


Class Cot 
a: number; 
b?: number; 


‘number | unde 


j 

let c = new C(); 

Gua 1 

c.a - undefined; // error, 'undefined' is not assignable to 'num 
ber' 

c.b = 13; 


c.b - undefined; // ok 
c.b = null; // error, 'null' is not assignable to 


4 


RAR do RAIS 


"number | unde 


由 于 可 以 为 null 的 类 型 是 通过 联合 类 型 实现 ， 那 么 你 需要 使 用 类 型 保护 来 去 


除 null 。 幸运 地 是 这 与 在 JavaScript 里 写 的 代码 一 致 : 


NO 


FUNCTION (sn. string | null): string sf 
if (sn == null) { 
return "default"; 


j 
else ( 

return sn; 
j 


这 里 很 明显 地 去 除了 null ， 你 也 可 以 使 用 短路 运算 符 : 


fune cronin (Shka string, | mu set ming st 
return sn || "default"; 


如 果 编 译 器 不 能 够 去 除 null 或 undefined ， 你 可 以 使 用 类 型 断言 手动 去 除 。 语 
法 是 添加 | BA: identifier! 从 identifier 的 类 型 里 去 除 
了 null 和 undefined 


function broken(name: string | null): string ( 
function postfix(epithet: string) { 
return name.charAt(O) + '. the ' + epithet; // error, 'name 
' is possibly null 
} 
name = name || "Bob"; 
return postfix("great"); 


function fixed(name: string | null): string { 
function postfix(epithet: string) { 
return name!.charAt(0) + '. the ' + epithet; // ok 
} 
name = name || "Bob"; 
return postfix("great"); 


KOEN TRE BR: AARMERLERRRKE BRK Hnull (除非 是 立即 调用 的 函 
ARAA) 9 HACHARBAHANRKRE BANA > LEERI PE 3 HM 
层 函 数 的 返回 值 。 如 果 无 法 知道 函数 在 哪里 被 调用 ， 就 无 法 知道 调用 时 name 的 


类 型 别名 


类 型 别名 会 给 一 个 类 型 起 个 新 名 字 。 类 型 别名 有 时 和 接口 很 像 ， 但 是 可 以 作用 于 原 
始 值 ， 联 合 类 型 ， 元 组 以 及 其 它 任 何 你 需要 手写 的 类 型 。 


type Name = string; 
type NameResolver = () => string; 
type NameOrResolver = Name | NameResolver; 
function getName(n: NameOrResolver): Name { 
if (typeof n === 'string') { 
return n; 
} 
else { 
return n(); 


起 别名 不 会 新 建 一 个 类 型 - 它 创 建 了 一 个 新 名 字 来 引用 那个 类 型 。 给 原始 类 型 起 别 
名 通常 没什么 用 ， 尽 管 可 以 做 为 文档 的 一 种 形式 使 用 。 


同 接口 一 样 ， 类 型 别名 也 可 以 是 泛 型 - 我 们 可 以 添加 类 型 参数 并 且 在 别名 声明 的 右 
侧 传 入 : 


type Container<T> = { value: T }; 


我 们 也 可 以 使 用 类 型 别名 来 在 属性 里 引用 自己 : 


type Tree<T> = { 
value: T; 
left: Tree<T>; 
right: Tree<T>; 


与 交 又 类 型 一 起 使 用 ， 我 们 可 以 创建 出 一 些 十 分 稀奇 古怪 的 类 型 。 


type LinkedList<T> = T & { next: LinkedList<T> }; 


interface Person { 
name: string; 


var people: LinkedList<Person>; 
var S = people.name; 


var s = people.next.name; 
var s = people.next.next.name; 
var s = people.next.next.next.name; 


然而 ， 类 型 别名 不 能 出 现在 声明 右 侧 的 任何 地 方 。 


type Yikes = Array<Yikes>; // error 


接口 vs. 类 型 别名 
像 我 们 提 到 的 ， 类 型 别名 可 以 像 接口 一 样 ; 然而 ， 仍 有 一 些 细微 差别 。 


名 字 一 比如 ? 错误 信息 就 不 会 使 用 别名 o 在 下 面 的 示例 代码 里 在 编译 器 中 将 gs 
Ale interfaced 上 ， 显 示 它 返回 的 是 Interface * 2A aliased 上 
时 ， 显 示 的 却 是 对 象 字 面 量 类 型 。 


type Alias = { num: number } 
interface Interface { 
num: number; 


} 


declare function aliased(arg: Alias): Alias; 
declare function interfaced(arg: Interface): Interface; 


另 一 个 重要 区 别 是 类 型 别名 不 能 被 extends 和 implements (自己 也 不 
能 extends 和 implements 其 它 类 型 ) 。 因为 软件 中 的 对 象 应 该 对 于 扩展 是 开 
放 的 ， 但 是 对 于 修改 是 封闭 的 ， 你 应 该 尽量 去 使 用 接口 代替 类 型 别名 。 


另 一 方面 ， 如 果 你 无 法 通过 接口 来 描述 一 个 类 型 并 且 需 要 使 用 联合 类 型 或 元 组 类 
型 ， 这 时 通常 会 使 用 类 型 别名 。 


字符 串 字 类 型 


字符 囊 字 面 量 类 型 多 许 你 指定 字符 囊 必须 的 固定 值 。 在 实际 应 用 中 ， 字 符 囊 字面 量 
类 型 可 以 与 联合 类 型 ， 类 型 保护 和 类 型 别名 很 好 的 配合 。 通过 结合 使 用 这 些 特性 ， 
你 可 以 实现 类 似 枚 举 类 型 的 字符 串 。 


type Easing = "ease-in" | "ease-out" | "ease-in-out"; 
class UlElement { 
animate(dx: number, dy: number, easing: Easing) ( 
if (easing --- "ease-in") ( 
2 
j 
else if (easing --- "ease-out") ( 
} 
else if (easing === "ease-in-out") { 
} 
else { 
// error! should not pass null or undefined. 


let button = new UIElement(); 

button.animate(0, 0, "ease-in"); 

button.animate(0, ©, "uneasy"); // error: "uneasy" is not allowe 
d here 


你 只 能 从 三 种 允许 的 字符 中 选择 其 一 来 做 为 参数 传递 ， 传 入 其 它 值 则 会 产生 错误 。 


Argument of type '"uneasy"' is not assignable to parameter of ty 
pe '"ease-in" | "ease-out" | "ease-in-out"' 


字符 串 字面 量 类 型 还 可 以 用 于 区 分 函数 重 载 : 


function createElement(tagName: "img"): HTMLImageElement; 
function createElement(tagName: "input"): HTMLInputElement; 


// ... more overloads 

function createElement(tagName: string): Element { 
// ... code goes here 

} 


数字 字面 量 类 型 


TypeScript 还 具有 数字 字面 量 类 型 。 
function roelilbie()= 1 | 29 $5 [4 13539561 
// naa 
我 们 很 少 直接 这 样 使 用 ， 但 它们 可 以 用 在 缩小 范围 调试 bug 的 时 候 : 


function foo(x: number) { 


ir x lee L |) x 1S] 2) Tt 
(ag ——— 
// Operator '!==' cannot be applied to types '1' and '2'. 


换 和 句 话说， 当 x 5 2 进行 比较 的 时 候 ， 它 的 值 必 须 为 1 ， 这 就 意味 着 上 面 的 比 
较 检 查 是 非法 的 。 


` `n 六 
枚 举 成 员 类 型 
如 我 们 在 枚 举 一 节 里 提 到 的 ， 当 每 个 枚 举 成 员 都 是 用 字面 量 初始 化 的 时 候 枚 举 成 员 
是 具有 类 型 的 。 


在 我 们 谈 及 “ 单 例 类 型 "的 时 候 ， 多 数 是 指 枚 举 成 员 类 型 和 数字 /字符 串 字面 量 类 
尽管 大 多 数 用 户 会 互 换 使 用 “ 单 例 类 型 "和 “字面 量 类 型 "。 


ed 
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可 辨识 联合 (Discriminated Unions) 


你 可 以 合并 单 例 类 型 ， 联 合 类 型 ， 类 型 保护 和 类 型 别名 来 创建 一 个 叫做 可 辨识 联合 
的 高 级 模式 ， 它 也 称 做 标签 联合 或 代数 数据 类 型 。 可 辨识 联合 在 函数 式 编程 很 有 用 
处 。 一 些 语言 会 自动 地 为 你 辨识 联合 ; 而 TypeScript 则 基于 已 有 的 JavaScript 模 

式 。 它 具有 3 个 要 素 : 


1. 具有 普通 的 单 例 类 型 属性 一 可 辨识 的 特征 。 


2. 一 个 类 型 别名 包含 了 那些 类 型 的 联合 一 联合 。 
3. 此 属性 上 的 类 型 保护 。 


interface Square { 
kind: "square"; 
size: number; 

} 

interface Rectangle { 
kind: "rectangle"; 
width: number; 
height: number; 

E 

interface Circle { 
kind: "circle": 
radius: number; 


首先 我 们 声明 了 将 要 联合 的 接口 。 每 个 接口 都 有 kind 属性 但 有 不 同 的 字符 串 字 
面 量 类 型 。 kind 属性 称 做 可 辨识 的 特征 或 标签 。 其它 的 属性 则 特定 于 各 个 接 
Wo 注意 ， 目 前 各 个 接口 间 是 没有 联系 的 。 下 面 我 们 把 它们 联合 到 一 起 : 


type Shape = Square | Rectangle | Circle; 


现在 我 们 使 用 可 辨识 联合 : 


function area(s: Shape) { 
switch (s.kind) { 
case "square": return s.size * s.size; 
case "rectangle": return s.height * s.width; 
case "circle": return Math.PI * s.radius ** 2; 


Ww 


当 没 有 涵盖 所 有 可 辨识 联合 的 变化 时 ， 我 们 想 让 编译 器 可 以 通知 我 们 。 比如 ， 如 果 
我 们 添加 了 Triangle 到 Shape ， 我 们 同时 还 需要 更 新 area: 


type Shape = Square | Rectangle | Circle | Triangle; 


function area(s: Shape) { 
switch (s.kind) { 
case "square": return s.size * s.size; 
case "rectangle": return s.height * s.width; 


case "circle": return Math.PI * s.radius ** 2; 


} 


// should error here - we didn't handle case "triangle" 


有 两 种 方式 可 以 实现 。 首先 是 局 用 --strictNullChecks 并 且 指 定 一 个 返回 值 类 


型 : 


function area(s: Shape): number { // error: returns number | und 


efined 
switch (s.kind) { 
case "square": return s.size * s.size; 
case "rectangle": return s.height * s.width; 


case "circle": return Math.PI * s.radius ** 2; 


AA switch 没有 包涵 所 有 情况 ， 所 以 TypeScript 认 为 这 个 函数 有 时 候 会 返 
回 undefined ° 如 果 你 明确 地 指定 了 返回 值 类 型 为 number ， 那 么 你 会 看 到 一 
个 错误 ， 因 为 实际 上 返回 值 的 类 型 为 number | undefined 。 然而 ， 这 种 方法 存 


在 些微 妙 之 处 且 --strictNullChecks 对 日 代码 支持 不 好 。 


第 二 种 方法 使 用 never 类 型 ， 编 译 器 用 它 来 进行 完整 性 检查 : 


function assertNever(x: never): never { 
throw new Error("Unexpected object: " + x); 


} 


function area(s: Shape) { 
switch (s.kind) { 
case "square": return s.size * s.size; 
case "rectangle": return s.height * s.width; 
case "circle": return Math.PI * s.radius ** 2; 
default: return assertNever(s); // error here if there a 
re missing cases 


j 


这 里 ， assertNever 检查 s 是 否 为 never 类 型 一 即 为 除去 所 有 可 能 情况 后 剩 下 
的 类 型 。 如 果 你 忘记 了 某 个 case， 那 么 s 将 具有 一 个 丨 实 的 类 型 并 且 你 会 得 到 一 
个 错误 。 这 种 方式 需要 你 定义 一 个 额外 的 函数 ， 但 是 在 你 忘记 某 个 case 的 时 候 也 更 


加 明显 。 


多 态 的 this 类 型 


SAM this 类 型 表示 的 是 某 个 包 钨 类 或 接口 的 子 类 型 。 这 被 称 做 请 bounded 多 态 
性 。 它 能 很 容易 的 表现 连贯 接口 间 的 继承 ， 比 如 。 在 计算 器 的 例子 里 ， 在 每 个 操 
作 之 后 都 返回 this 类 型 : 


class BasicCalculator { 

public constructor(protected value: number = 0) { } 

public currentValue(): number { 
return this.value; 

} 

public add(operand: number): this { 
this.value += operand; 
return this; 

} 

public multiply(operand: number): this { 
this.value *= operand; 
return this; 


} 
// ... other operations go here ... 
} 
let v = new BasicCalculator(2) 
.multiply(5) 
.add(1) 


.currentValue(); 


由 于 这 个 类 使 用 了 this 类 型 ， 你 可 以 继承 它 ， 新 的 类 可 以 直接 使 用 之 前 的 方法 ， 
不 需要 做 任何 的 改变 。 


class ScientificCalculator extends BasicCalculator { 
public constructor(value = 0) { 
super (value); 
J 
public sin() ( 
this.value - Math.sin(this.value); 
return this; 


j 
// ... other operations go here ... 
j 
let v = new ScientificCalculator(2) 
.multiply(5) 
.Sin() 
.add(1) 


.currentValue(); 


如 果 没 有 this 类 型 ， ScientificCalculator 就 不 能 够 在 继 

Æ BasicCalculator 的 同时 还 保持 接口 的 连贯 性 。 multiply 将 会 返 
回 BasicCalculator ， 它 并 没有 sin 方法 。 然而 ， 使 用 this X 
Al > multiply 会 返回 this ， 在 这 里 就 是 ScientificCalculator ° 


索引 类 型 (Index types) 


使 用 索引 类 型 ， 编 译 器 就 能 够 检查 使 用 了 动态 属性 名 的 代码 。 例如 ， 一 个 常见 的 
JavaScript 模 式 是 从 对 象 中 选取 属性 的 子 集 。 


function pluck(o, names) { 
return names.map(n => o[n]); 


下 面 是 如 何在 TypeScript 里 使 用 此 函数， 通过 索引 类 型 查询 和 索引 访问 操作 符 : 


function pluck<T, K extends keyof T»2(o: T, names: K[]): T[K][] 1 
return names.map(n -» o[n]); 


interface Person ( 
name: string; 
age: number; 
} 
let person: Person = { 
name: 'Jarid', 
age: 35 
J; 
let strings: string[] = pluck(person, ['name']); // ok, string[] 


编译 器 会 检查 name HFA Person 的 一 个 属性 。 本 例 还 引入 了 几 个 新 的 类 
型 操作 符 。 首 先是 keyof T ， 索 引 类 型 查询 操作 符 。 对 于 任何 类 型 T > keyof 
T 的 结果 为 T 上 已 知 的 公共 属性 名 的 联合 。 例如: 


let personProps: keyof Person; // 'name' 'age' 

keyof Person 是 完全 可 以 与 'name' | 'age' 互相 替换 的 。 不同 的 是 如 果 你 添 
加 了 其 它 的 属性 到 Person ， 例 如 address: string >? 7f A keyof Person 会 
自动 变 为 'name' | 'age' | 'address' 。 你 可 以 在 像 pluck 函数 这 类 上 下 文 


里 使 用 keyof ， 因为 在 使 用 之 前 你 并 不 清楚 可 能 出 现 的 属性 名 。 但 编译 器 会 检查 
你 是 否 传 入 了 正确 的 属性 名 给 pluck 


pluck(person, ['age', 'unknown']); // error, 'unknown' is not in 


'name' | 'age' 


第 二 个 操作 符 是 TIK] > RIG ARR o 在 这 里 ， 类 型 语法 反映 了 表达 式 语 
法 。 这 意味 着 person['name'] 具有 类 型 Person['name'] 一 在 我 们 的 例子 里 
WMA string 类 型 。 然 而， 就 像 索 引 类 型 查询 一 样 ， 你 可 以 在 普通 的 上 下 文 里 使 
用 T[K] ， 这 正 是 它 的 强大 所 在 。 你 只 要 确保 类 型 变量 K extends keyof T 就 
可 以 了 。 例如 下 面 getProperty 函数 的 例子 : 


function getProperty<T, K extends keyof T»(o: T, name: K): T[K] 
{ 


return o[name]; // o[name] is of type T[K] 


getProperty 里 的 o: T 和 name: K ， 意 味 着 o[name]: T[K] ° 当 你 返 
E T[K] 的 结果 ， 编 译 器 会 实例 化 键 的 趴 实 类 型 ， 因 此 getProperty 的 返回 值 类 
型 会 随 着 你 需要 的 属性 改变 。 


let name: string = getProperty(person, 'name'); 

let age: number = getProperty(person, 'age'); 

let unknown - getProperty(person, 'unknown'); // error, 'unknown 
' is not in 'name' | 'age' 


索引 类 型 和 字符 串 索 引 签 名 


keyof 和 T[K] 与 字符 串 索引 签名 进行 交互 。 如 果 你 有 一 个 带 有 字符 串 索 引 签 名 
的 类 型 ， 那 么 keyof T 会 是 string ° 并且 T[string] 为 索引 签名 的 类 型 : 


interface Map<T> { 
[key: string]: T 
} 
let keys: keyof Map<number>; // string 
let value: Map<number>['foo']; // number 


映射 类 型 
一 个 常见 的 任务 是 将 一 个 已 知 的 类 型 每 个 属性 都 变 为 可 选 的 : 


interface PersonPartial { 
name?: string; 
age?: number; 


或 者 我 们 想 要 一 个 只 读 版 本 : 


interface PersonReadonly { 
readonly name: string; 
readonly age: number; 


R f£ JavaScript € € 3$ IL > TypeScriptae HT Wie X UP Ole HARA HTN 
一 映射 类 型 。 在 映射 类 型 里 ， 新 类 型 以 相同 的 形式 去 转换 昌 类 型 里 每 个 属性 。 例 
如 ， 你 可 以 令 每 个 属性 成 为 readonly 类 型 或 可 选 的 。 下面 是 一 些 例子 : 


type Readonly<T> = { 

readonly [P in keyof T]: T[P]; 
} 
type Partial<T> = { 

[P in keyof T]?: T[P]; 


像 下 面 这 样 使 用 : 


type PersonPartial = Partial<Person>; 
type ReadonlyPerson = Readonly<Person>; 


下 面 来 看 看 最 简单 的 映射 类 型 和 它 的 组 成 部 分 : 


type Keys = ‘optioni' | 'option2'; 
type Flags = { [K in Keys]: boolean }; 


它 的 语法 与 索引 签名 的 语法 类 型 ， 内 部 使 用 了 for.. in » 具有 三 个 部 分 : 


1. 类 型 变量 K ， 它 会 依次 绑 定 到 每 个 属性 。 
2. 字符 串 字 面 量 联合 的 Keys ， 它 包含 了 要 迭代 的 属性 名 的 集合 。 
3. 属性 的 结果 类 型 。 


在 个 简单 的 例子 里 ， Keys 是 硬 编码 的 的 属性 名 列表 并 且 属 性 类 型 永远 
X boolean ， 因 此 这 个 映射 类 型 等 同 于 : 


type Flags = { 
optioni1: boolean; 
option2: boolean; 


dE AGE RS RAL TRAM TL Readonly X Partial 。 它们 会 基于 一 些 
已 存在 的 类 型 ， 且 按照 一 定 的 方式 转换 字段 。 这 就 是 keyof 和 索引 访问 类 型 要 做 
的 事情 


type NullablePerson = { [P in keyof Person]: Person[P] | null } 
type PartialPerson = { [P in keyof Person]?: Person[P] } 


它 更 有 用 的 地 方 是 可 以 有 一 些 通用 版 本 。 


type Nullable<T> = { [P in keyof T]: T[P] | null } 
type Partial<T> = { [P in keyof T]?: T[P] } 


在 这 些 例子 里 ， 属 性 列表 是 keyof T 且 结 果 类 型 是 T[P] 的 变 体 。 这 是 使 用 通用 
映射 类 型 的 一 -o 因为 这 类 转换 是 同 态 的 ， 了 映射 只 作用 于 T 的 属性 而 没有 
其 它 的 。 编译 器 知道 在 添加 任何 新 属性 之 前 可 以 找 贝 所 有 存在 的 属性 修饰 符 。 例 

如 ， 假 设 Person.name 是 只 读 的 ， 那 么 Partial«Person».name 也 将 是 只 读 的 


且 为 可 选 的 。 


下 面 是 另 一 个 例子 ，T[P] 被 包装 在 Proxy<T> 类 里 : 


type Proxy<T> = { 
get(): T 
set(value: T): void; 
j 
type Proxify<T> = { 
[P in keyof T]: Proxy<T[P]>; 


j 

function Prox iiy- TACO) oxify<T> { 
// ... Wrap proxies 

j 


let proxyProps - proxify(props); 


注意 Readonly«T» 和 Partial«T» 用 处 不 小 ， 因 此 它们 与 Pick 和 Record 一 
同 被 包含 进 了 TypeScript 的 标准 库 里 : 


type Pick<T, K extends keyof T> = { 
IR an KIE TIRI; 


} 

type Record<K extends string, T> = { 
[P in K]: T 

} 


Readonly * Partial 和 Pick 是 同 态 的 ， 但 Record 不 是 。 因为 Record 并 
不 需要 输入 类 型 来 拷贝 属性 ， 所 以 它 不 属于 同 态 : 


type ThreeStringProps = Record<'propi' | 'prop2' | 'prop3', stri 
ng> 


非 同 态 类 型 本 质 上 会 创建 新 的 属性 ， 因 此 它们 不 会 从 它 处 拷贝 属性 修饰 符 。 


由 映射 类 型 进行 推断 


现在 你 了 解 了 如 何 包装 一 个 类 型 的 属性 ， 那 么 接 下 来 就 是 如 何 拆 包 。 其 实 这 也 非常 
BI: 


fUNCTLOM ünproxifysre(t: (Proxify<t>): T { 
let result = {} as T; 
for (const k in t) { 
result[k] = t[k].get(); 
j 


return result; 


Ww 


let originalProps = unproxify(proxyProps); 


注意 这 个 拆 包 推断 只 适用 于 同 态 的 映射 类 型 。 如 果 映 射 类 型 不 是 同 态 的 ， 那 么 需要 
给 拆 包 函数 一 个 明确 的 类 型 参数 。 
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É ECMAScript 20152 > symbol 成 为 了 一 种 新 的 原生 类 型 ， 就 
像 number 和 string 一 样 。 


symbol 类 型 的 值 是 通过 Symbol 构造 函数 创建 的 。 
let symi = Symbol(); 


let sym2 = Symbol("key"); // 可 选 的 字符 串 key 


Symbols 是 不 可 改变 且 唯 一 的 。 


let sym2 = Symbol("key"); 
let sym3 = Symbol("key"); 


sym2 === sym3; // false, symbols "E— $J 


像 字 符 串 一 样 ，symbols 也 可 以 被 用 做 对 象 属性 的 键 。 
let sym = Symbol(); 
let obj = { 
[sym]: "value" 


e 


console.log(obj[sym]); // "value" 


Symbols 也 可 以 与 计算 出 的 属性 名 声明 相 结合 来 声明 对 象 的 属性 和 类 成 员 。 


const getClassNameSymbol = Symbol(); 


class C { 
[getClassNameSymbol]()1 
return "C^ 
j 
j 


let c = new C(); 
let className - c[getClassNameSymbol](); 


众所周知 的 Symbols 


除了 用 户 定义 的 symbols， 还 有 一 些 已 经 众所周知 的 内 置 symbols。 内 置 symbols 用 
来 表示 语言 内 部 的 行为 。 


以 下 为 这 些 symbols 的 列表 : 
Symbol .hasInstance 


方法 ， 会 被 instanceof 运算 符 调 用 。 构 造 器 对 象 用 来 识别 一 个 对 象 是 否 是 其 实 
例 o 


Symbol.isConcatSpreadable 


布尔 值 ， 表 示 当 在 一 个 对 象 上 调用 Array.prototype.concat 时 ， 这 个 对 象 的 数 
组 元 素 是 否 可 展开 。 


Symbol.iterator 


方法 ， 被 for-of 语句 调用 。 返 回 对 象 的 默认 述 代 器 。 


Symbol.match 


方法 ， 被 String.prototype.match 调用 。 正 则 表达 式 用 来 匹配 字符 串 。 


Symbol. replace 


方法 ， 被 String.prototype.replace 调用 。 正 则 表达 式 用 来 替换 字符 串 中 匹配 
的 子囊 。 


Symbol.search 


方法 ， 被 String.prototype.search 调用 。 正 则 表达 式 返回 被 匹配 部 分 在 字符 串 
中 的 索引 。 


Symbol .species 


Heh > A—AAW7E BHA o MROBRERN F © 
Symbol. split 

方法 ， 被 String.prototype.split 调用 。 正 则 表达 式 来 用 分 割 字 符 囊 。 
Symbol .toPrimitive 


方法 ， 被 ToPrimitive 抽象 操作 调用 。 把 对 象 转换 为 相应 的 原始 值 。 


Symbol .toStringTag 


方法 ， 被 内 置 方法 Object.prototype.toString 调用 。 返 回 创建 对 象 时 默认 的 
字符 串 描述 。 


Symbol .unscopables 


对 象 ， 它 自己 拥有 的 属性 会 被 with 作用 域 排除 在 外 。 


"p Ik ARE 

当 一 个 对 象 实 现 了 symbol.iterator A Eit > X129 CATARI o 一 些 内 置 
的 类 型 

如 Array ^ Map ，Set ，String ， Int32Array * Uint32Array 等 都 已 
经 实现 了 各 自 的 Symbol.iterator ° 对 象 上 的 symbol.iterator 函数 负责 返 


回 供 和 迭代 的 值 。 


for. .of 语句 


for..of 会 遍历 可 和 迭代 的 对 象 ， 调 用 对 象 上 的 symbol.iterator 方法 。 下 面 是 
在 数组 上 使 用 for..of 的 简单 例子 : 


let someArray = [1, "String", false]; 
for (let entry of someArray) { 


console.log(entry); // 1, "string", false 


for..of vs. for..in 74 


for..of 和 for..in 均 可 和 迭代 一 个 列表 ; 但 是 用 于 和 迭代 的 值 却 不 


同 ， for..in 迭代 的 是 对 象 的 键 的 列表 ， 而 for..of 则 和 迭代 对 象 的 键 对 应 的 


值 。 
下 面 的 例子 展示 了 两 者 之 间 的 区 别 : 


let list = [4, 5, 6]; 


for (let 1 in list) f 
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for (let i of list) { 
console.log(i); // KA "Su. "oM 


另 一 个 区 别 是 for..in 可 以 操作 任何 对 象 ; 它 提供 了 查看 对 象 属性 的 一 种 方法 。 
但 是 for..of 关注 于 和 迭代 对 象 的 值 。 内 置 对 象 Map 和 Set 已 经 实现 
了 Symbol.iterator 方法 ， 让 我 们 可 以 访问 它们 保存 的 值 。 


let pets = new Set(["Cat", "Dog", "Hamster"]); 
pets["species"] = "mammals"; 


for (let pet in pets) { 
console.log(pet); // "species" 


for (let pet of pets) { 
console.log(pet); // "Cat", "Dog", "Hamster" 


代码 生成 


目标 为 ES5 和 ES3 


当 生 成 目标 为 ES5 或 ES3， 和 迭代 器 只 允许 在 Array 类 型 上 使 用 。 在 非 数组 值 上 使 
用 for..of 语句 会 得 到 一 个 错误 ， 就 算 这 些 非 数 组 值 已 经 实现 
了 Symbol.iterator 属性 。 


编译 器 会 生成 一 个 简单 的 for 循环 做 为 for..of 循环 ， 比 如 : 


let numbers = [1, 2, 3]; 
for (let num of numbers) { 
console.log(num); 


生成 的 代码 为 : 


var numbers = [1, 2, 3]; 

for (var _i = 0; i < numbers.length; _i++) { 
var num = numbers[ i]; 
console. log(num) ; 


H 4A ECMAScript 2015 或 更 高 


当 目 标 为 兼容 ECMAScipt 2015 的 引擎 时 ， 编 译 器 会 生成 相应 引擎 的 for. .of 内 
LARS EMA A c 


关于 术语 的 一 点 说 明 : 请 务必 注意 一 点 ，TypeScript 1.5 € REL CLARET E 
化 。“ 内 部 模块 "现在 称 做 "命名 空间 ”。“ 外 部 模块 "现在 则 简称 为 “模块 ”， 这 是 为 
了 与 ECMAScript 2015 里 的 术语 保持 一 致 ，( 也 就 是 说 module x { 相当 于 现 


在 推荐 的 写法 namespace X { )。 
介绍 
从 ECMAScript 2015 开 始 ，JavaScript 引 入 了 模块 的 概念 。TypeScript 也 沿用 这 个 概 


模块 在 其 自身 的 作用 域 里 执行 ， 而 不 是 在 全 局 作用 域 里 ; 这 意味 着 定义 在 一 个 模块 
里 的 变量 ， 函 数 ， 类 等 等 在 模块 外 部 是 不 可 见 的 ， 除 非 你 明确 地 使 用 export 形式 
之 一 导出 它们 。 相反 ， 如 果 想 使 用 其 它 模块 导出 的 变量 ， 函 数 ， 类 ， 接 口 等 的 时 
候 ， 你 必须 要 导入 它们 ， 可 以 使 用 import 形式 之 一 。 


模块 是 自 声明 的 ; 两 个 模块 之 间 的 关系 是 通过 在 文件 级 别 上 使 用 imports 和 exports 
建立 的 。 


模块 使 用 模块 加 载 器 去 导入 其 它 的 模块 。 在 运行 时 ， 模 块 加 载 器 的 作用 是 在 执行 此 
模块 代码 前 去 查找 并 执行 这 个 模块 的 所 有 依赖 。 大 家 最 熟知 的 JavaScript 模 块 加 载 
器 是 服务 于 Node.js 的 CommonJS 和 服务 于 Web 应 用 的 Require.js。 


TypeScript 5 ECMAScript 2015 一 样 ， 任 何 包 含 顶 级 import 或 者 export 的 文件 
都 被 当成 一 个 模块 。 相 反 地 ， 如 果 一 个 文件 不 带 有 顶级 的 import 或 
者 export 声明 ， 那 么 它 的 内 容 被 视 为 全 局 可 见 的 (因此 对 模块 也 是 可 见 的 ) e 


导出 


导出 声明 


任何 声明 (比如 变量 ， 函 数 ， 类 ， 类 型 别名 或 接口 ) 都 能 够 通过 添加 export 关键 


Validation.ts 


export interface StringValidator { 
isAcceptable(s: string): boolean; 


ZipCodeValidator.ts 


export const numberRegexp = /A[0-9]+$/; 
export class ZipCodeValidator implements StringValidator { 


isAcceptable(s: string) { 
return s.length === 5 && numberRegexp.test(s); 


5 de 


导出 语 名 很 便利 ， 因 为 我 们 可 能 需要 对 导出 的 部 分 重 命名 ， 所 以 上 面 的 例子 可 以 这 
样 改 写 : 


class ZipCodeValidator implements StringValidator { 


isAcceptable(s: string) { 
return s.length === 5 && numberRegexp.test(s); 


} 
export { ZipCodeValidator }; 


export { ZipCodeValidator as mainValidator }; 


重新 导出 


我 们 经 常会 去 扩展 其 它 模块 ， 并 且 只 导出 那个 模块 的 部 分 内 容 。 重新 导出 功能 并 不 
会 在 当前 模块 导入 那个 模块 或 定义 一 个 新 的 局 部 变量 。 


ParselntBasedZipCodeValidator.ts 


export class ParseIntBasedZipCodeValidator { 
isAcceptable(s: string) { 
return s.length === 5 && parseInt(s).toString() === s; 


// 导出 原先 的 验证 器 但 做 了 重 命名 
export {ZipCodeValidator as RegExpBasedZipCodeValidator} from ". 
/ZipCodeValidator"; 


或 者 一 个 模块 可 以 包 训 多 个 模块 ， 并 把 他 们 导出 的 内 容 联 合 在 一 起 通过 语 


法 : export * from "module" ° 


AllValidators.ts 


export * from "./StringValidator"; // exports interface StringVa 
lidator 

export * from "./LettersOnlyValidator"; // exports class Letters 
OnlyValidator 

export * from "./ZipCodeValidator"; // exports class ZipCodeVal 
idator 


导入 


模块 的 导入 操作 与 导出 一 样 简单 。 可 以 使 用 以 下 import 形式 之 一 来 导入 其 它 模 
块 中 的 导出 内 容 。 


导入 一 个 模块 中 的 某 个 导出 内 容 


import { ZipCodeValidator } from "./ZipCodeValidator"; 


let myValidator = new ZipCodeValidator(); 


可 以 对 导入 内 容重 命名 


import { ZipCodeValidator as ZCV } from "./ZipCodeValidator"; 
let myValidator = new ZCV(); 


将 整个 模块 导入 到 一 个 变量 ， 并 通过 它 来 访问 模块 
的 导出 部 分 


import * as validator from "./ZipCodeValidator"; 
let myValidator = new validator.ZipCodeValidator(); 


具有 副作用 的 导入 模块 


管 不 推荐 这 么 做 ， 一 些 模块 会 设置 一 些 全 局 状态 供 其 它 模块 使 用 。 这 些 模块 可 能 
2l 0022255 50925 5505 


import "./my-module.js"; 


默认 导出 


每 个 模块 都 可 以 有 一 个 default 导出 。 默认 导出 使 用 default 关键 字 标 记 ; 并 
且 一 个 模块 只 能 够 有 一 个 default 导出 。 需要 使 用 一 种 特殊 的 导入 形式 来 导 
A default 导出 。 


default 导出 十 分 便利 。 比 如 ， 像 JQuery 这 样 的 类 库 可 能 有 一 个 默认 导 
出 jQuery 或 $ ， 并 且 我 们 基本 上 也 会 使 用 同样 的 名 字 jQuery 或 $ 导出 
JQuery ° 


JQuery.d.ts 


declare let $: JQuery; 
export default $; 


App.ts 


import $ from "JQuery"; 


$("button.continue").html( "Next Step..." ); 


类 和 函数 声明 可 以 直接 被 标记 为 默认 导出 。 标记 为 默认 导出 的 类 和 函数 的 名 字 是 可 
以 省 略 的 。 


ZipCodeValidator.ts 


export default class ZipCodeValidator { 
static numberRegexp = /^[0-9]-*4$/; 
isAcceptable(s: string) { 
return s.length --- 5 && ZipCodeValidator.numberRegexp.t 
est(s); 


} 


Test.ts 


import validator from "./ZipCodeValidator"; 


let myValidator = new validator(); 


或 者 


StaticZipCodeValidator.ts 


const numberRegexp = /^[0-9]-*$/; 


export default function (s: string) 1 
return s.length --- 5 && numberRegexp.test(s); 


Test.ts 


import validate from "./StaticZipCodeValidator"; 
let strings = ["Hello", "98052", "101"]; 


// Use function validate 
strings.forEach(s => { 
console.log( "${s}" ${validate(s) ? " matches" : " does not ma 
tch"} ); 
3); 


default 导出 也 可 以 是 一 个 值 


OneTwoThree.ts 


export default "123"; 


Log.ts 


import num from "./OneTwoThree"; 


console.log(num); // "123" 


export = 和 import = require() 


CommonJS 和 AMD 都 有 一 个 exports 对 象 的 概念 ， 它 包含 了 一 个 模块 的 所 有 导出 
内 容 。 

它们 也 支持 把 exports 替换 为 一 个 自 定 义 对 象 。 默认 导出 就 好 比 这 样 一 个 功能 ; 
然而 ， 它 们 却 并 不 相互 兼容 。 TypeScript 模 块 支持 export = 语法 以 支持 传统 的 
CommonJS 和 AMD 的 工作 流 模 型 。 

export = 语法 定义 一 个 模块 的 导出 对 象 。 它 可 以 是 类 ， 接 口 ， 命 名 空间 ， 函 数 
或 枚 举 。 

若 使 用 export = 导出 一 个 模块 ， 则 必须 使 用 TypeScript 的 特定 语法 import 
module = require("module") 来 导入 此 模块 。 


ZipCodeValidator.ts 


let numberRegexp = /^[0-9]-*$/; 
class ZipCodeValidator { 
isAcceptable(s: string) { 
return s.length === 5 && numberRegexp.test(s); 


} 
export = ZipCodeValidator; 


Test.ts 


import zip = require("./ZipCodeValidator"); 


// Some samples to try 
let strings = ["Hello", "98052", "101"]; 


// Nalidators to use 
let validator - new zip(); 


// Show whether each string passed each validator 
strings.forEach(s => { 

console.log( "${ s }" - $( validator.isAcceptable(s) ? "matche 
s 3 "does not match" } ); 


3): 


生成 模块 代码 


根据 编译 时 指定 的 模块 目标 参数 ， 编 译 器 会 生成 相应 的 供 Node.js (CommonJS)， 

Require.js (AMD) > UMD, SystemJS 或 ECMAScript 2015 native modules (ES6) 模 

块 加 载 系统 使 用 的 代码 。 想 要 了 解 生 成 代码 中 define ， require 和 
register 的 意义 ， 请 参考 相应 模块 加 载 器 的 文档 。 


下 面 的 例子 说 明了 导入 导出 语句 里 使 用 的 名 字 是 怎么 转换 为 相应 的 模块 加 载 器 代码 
的 。 


SimpleModule.ts 


import m = require("mod"); 
export let t = m.something + 1; 


AMD / RequireJS SimpleModule.js 


define(["require", "exports", "./mod"], function (require, expor 


bs modi) 1 
exports.t = mod 1.something + 1; 


3); 


CommonJS / Node SimpleModule.js 


require("./mod"); 
mod 1.something + 1; 


let mod 1 
exports.t 


UMD SimpleModule.js 


(function (factory) { 


if (typeof module --- "object" && typeof module.exports --- 
"object") ( 
let v - factory(require, exports); if (v !-- undefined) 
module.exports - v; 
} 
else if (typeof define === "function" && define.amd) { 
define(["require", "exports", "./mod"], factory); 
} 


})(function (require, exports) { 
let mod_1 = require("./mod"); 
exports.t = mod_1.something + 1; 


3); 


System SimpleModule.js 


System.register(["./mod"], function(exports 1) { 
let mod 1; 
let t; 
return { 
setters:[ 
function (mod-1 1) f 
mod 1 - mod 1 1; 
j], 


execute: function() { 
exports 1("t", t = mod 1.something + 1); 


3); 


Native ECMAScript 2015 modules SimpleModule.js 


import ( something ) from "./mod"; 
export let t = something + 1; 


大 大 > 一 
简单 示例 
下 面 我 们 来 整理 一 下 前 面 的 验证 器 实现 ， 每 个 模块 只 有 一 个 命名 的 导出 。 


为 了 编译 ， 我 们 必需 要 在 命令 行 上 指定 一 个 模块 目标 。 对 于 Node.js 来 说 ， 使 用 -- 
module commonjs ; 对 于 Require.js 来 说 ， 使 用 --module amd 。 上 比如 : 


tsc --module commonjs Test.ts 


编译 完成 后 ， 每 个 模块 会 生成 一 个 单独 的 .js 文件 。 好比 使 用 了 reference 标 签 ， 
编译 器 会 根据 import 语句 编译 相应 的 文件 。 


Validation.ts 


export interface StringValidator { 
isAcceptable(s: string): boolean; 


LettersOnlyValidator.ts 


import { StringValidator } from "./Validation"; 
const lettersRegexp = /A[A-Za-z]+$/; 
export class LettersOnlyValidator implements StringValidator { 


isAcceptable(s: string) { 
return lettersRegexp.test(s); 


ZipCodeValidator.ts 


import ( StringValidator ) from "./Validation"; 
const numberRegexp = /^[0-9]-*$/; 
export class ZipCodeValidator implements StringValidator { 


isAcceptable(s: string) { 
return s.length === 5 && numberRegexp.test(s); 


Test.ts 


import { StringValidator } from "./Validation"; 
import { ZipCodeValidator } from "./ZipCodeValidator"; 
import { LettersOnlyValidator } from "./LettersOnlyValidator"; 


// Some samples to try 
let strings = ["Hello", "98052", "101"]; 


// Validators to use 

let validators: { [s: string]: StringValidator; } = {}; 
validators["ZIP code"] = new ZipCodeValidator(); 
validators["Letters only"] = new LettersOnlyValidator(); 


// Show whether each string passed each validator 
strings.forEach(s => { 
for (let name in validators) { 
console.log( "${ s }" - ${ validators[name].isAcceptable 
(s) ? "matches" : "does not match" } ${ name }`); 


} 
3): 


可 选 的 模块 加 载 和 其 它 高 级 加 载 场景 


有 时 候 ， 你 只 想 在 某 种 条 件 下 才 加 载 某 个 模块 。 在 TypeScript 里 ， 使 用 下 面 的 方式 
来 实现 它 和 其 它 的 高 级 加 载 场景 ， 我 们 可 以 直接 调用 模块 加 载 器 并 且 可 以 保证 类 型 


>A 


测 是 否 每 个 模块 都 会 在 生成 的 JavaScript 中 用 到 。 如 果 一 个 模块 标识 符 
只 在 类 型 注解 部 分 使 用 ， 并 且 完 全 没有 在 表达 式 中 使 用 时 ， 就 不 会 生 
成 require 这 个 模块 的 代码 。 省 略 掉 没有 用 到 的 引用 对 性 能 提升 是 很 有 益 的 ， 并 
同时 提供 了 选择 性 加 载 模块 的 能 力 。 


这 种 模式 的 核心 是 import id = require("...") 语句 可 以 让 我 们 访问 模块 导出 
的 类 型 。 模 块 加 载 器 会 被 动态 调用 (通过 require ) ， 就 像 下 面 if 代码 块 里 那 
样 。 它 利用 了 省 略 引 用 的 优化 ， 所 以 模块 只 在 被 需要 时 加 载 。 为 了 让 这 个 模块 工 
作 ， 一 定 要 注意 import 定义 的 标识 符 只 能 在 表示 类 型 处 使 用 (不 能 在 会 转换 成 

JavaScript 的 地 方 ) 。 


为 了 确保 类 型 安全 性 ， 我 们 可 以 使 用 typeof K# Fe typeof 关键 字 ， 当 在 表 
示 类 型 的 地 方 使 用 时 ， 会 得 出 一 个 类 型 值 ， 这 里 就 表示 模块 的 类 型 。 


示例 : Node.js 里 的 动态 模块 加 载 
declare function require(moduleName: string): any; 
import { ZipCodeValidator as Zip } from "./ZipCodeValidator"; 


if (needZipValidation) { 

let ZipCodeValidator: typeof Zip = require("./ZipCodeValidat 
or"); 

let validator = new ZipCodeValidator(); 

if (validator.isAcceptable("...")) { /* ... */ } 


示例 : require.js 里 的 动态 模块 加 载 


declare function require(moduleNames: string[], onLoad: (...args 
: any[]) => void): void; 


import * as Zip from "./ZipCodeValidator"; 


if (needZipValidation) ( 
require(["./ZipCodeValidator"], (ZipCodeValidator: typeof Zi 
p) => { 
let validator = new ZipCodeValidator.ZipCodeValidator(); 
if (validator.isAcceptable("...")) ( /* ... */ } 


3); 


示例 : System.js 里 的 动态 模块 加 载 


declare const System: any; 
import { ZipCodeValidator as Zip } from "./ZipCodeValidator"; 


if (needZipValidation) { 
System. import("./ZipCodeValidator").then((ZipCodeValidator: 
typeof Zip) => { 
var x = new ZipCodeValidator(); 
uro rsAcceptable( yy d 5 ic S 
3); 


使 用 其 它 的 JavaScript 库 


要 想 描述 非 TypeScript 编 写 的 类 库 的 类 型 ， 我 们 需要 声明 类 库 所 暴露 出 的 API 。 


我 们 叫 它 声明 因为 它 不 是 “外 部 程序 "的 具体 实现 。 它们 通常 是 在 .d.ts 文件 里 定 
义 的 。 如 果 你 熟悉 C/C++， 你 可 以 把 它们 当做 .h 文件 。 让 我 们 看 一 些 例子 。 


外 部 模 : 


在 Node.js 里 大 部 分 工作 是 通过 加 载 一 个 或 多 个 模块 实现 的 。 我 们 可 以 使 用 顶级 
的 export 声明 来 为 每 个 模块 都 定义 一 个 .d.ts 文件 ， 但 最 好 还 是 写 在 一 个 大 
的 .d.ts 文件 里 。 我 们 使 用 与 构造 一 个 外 部 命名 空间 相似 的 方法 ， 但 是 这 里 使 
用 module 关键 字 并 且 把 名 字 用 引号 括 起 来 ， 方 便 之 后 import ° 例如 : 


node.d.ts (simplified excerpt) 


declare module "url" { 
export interface Url { 
protocol?: string; 
hostname?: string; 
pathname?: string; 


export function parse(urlStr: string, parseQueryString?, sla 
shesDenoteHost?): Url; 


j 
declare module "path" { 
export function normalize(p: string): string; 


export function Jom a paths rany Ne string; 
export let sep: string; 


现在 我 们 可 以 /// «reference»  node.d.ts 并 且 使 用 import url = 
require("url"); 或 import * as URL from "url" 加 载 模块 。 


/// <reference path="node.d.ts"/> 
import * as URL from "url"; 
let myUrl = URL.parse("http://www.typescriptlang.org"); 


外 部 模块 简写 


假如 你 不 想 在 使 用 一 个 新 模块 之 前 花 时 间 去 编写 声明 ， 你 可 以 采用 声明 的 简写 形式 
以 便 能 够 快速 使 用 它 。 


declarations.d.ts 


declare module "hot-new-module"; 


简写 模块 里 所 有 导出 的 类 型 将 是 any 。 


import x, {y} from "hot-new-module"; 
x(y); 


模块 声明 通配符 


某 些 模块 加 载 器 如 SystemJS 和 AMD 支 持 导 入 非 JavaScript 内 容 。 它们 通常 会 使 用 
一 个 前 级 或 后 级 来 表示 特殊 的 加 载 语法 。 模块 声明 通配符 可 以 用 来 表示 这 些 情况 。 


declare module "*!text" { 
const content: string; 
export default content; 


} 


// Some do it the other way around. 
declare module "json!*" { 

const value: any; 

export default value; 


现在 你 可 以 就 导入 匹配 "* text" 或 "json!*" 的 内 容 了 。 


import fileContent from "./xyz.txt!text"; 
import data from "json!http://example.com/data.json"; 
console.log(data, fileContent); 


UMD 模块 

有 些 模块 被 设计 成 兼容 多 个 模块 加 载 器 ， 或 者 不 使 用 模块 加 载 器 (全 局 变量 ) 。 € 
们 以 UMD 模块 为 代表 。 这 些 库 可 以 通过 导入 的 形式 或 全 局 变量 的 形式 访问 。 例 
dm : 


math-lib.d.ts 


export function isPrime(x: number): boolean; 
export as namespace mathLib; 


之 后 ， 这 个 库 可 以 在 某 个 模块 里 通过 导入 来 使 用 : 


import { isPrime } from "math-lib"; 
isPrime(2); 
mathLib.isPrime(2); // ERROR: can't use the global definition fr 


om inside a module 


它 同样 可 以 通过 全 局 变量 的 形式 使 用 ， 但 只 能 在 某 个 脚本 里 。 (脚本 是 指 一 个 不 带 
有 导入 或 导出 的 文件 。) 


mathLib.isPrime(2); 


创建 模块 结构 指导 
能 地 在 顶层 导出 


用 户 应 该 更 容易 地 使 用 你 模块 导出 的 内 容 。 上 获 套 层次 过 多 会 变 得 难以 处 理 ， 因 此 仔 
细 考 虑 一 下 如 何 组 织 你 的 代码 。 

从 你 的 模块 中 导出 一 个 命名 空间 就 是 一 个 增加 黎 套 的 例子 。 虽然 命名 空间 有 时 候 有 
它们 的 用 处 ， 在 使 用 模块 的 时 候 它 们 额外 地 增加 了 一 层 。 这 对 用 户 来 说 是 很 不 便 的 
并 且 通 常 是 多 余 的 。 

导出 类 的 静态 方法 也 有 同样 的 问题 - 这 个 类 本 身 就 增加 了 一 层 诅 套 。 除 非 它 能 方便 
表述 或 便于 清晰 使 用 ， 否 则 请 考虑 直接 导出 一 个 辅助 方法 。 


如 果 仅 导出 单个 class 或 function ， 使 用 
export default 


就 像 "在 顶层 上 导出 ”帮助 减少 用 户 使 用 的 难度 ， 一 个 默认 的 导出 也 能 起 到 这 个 效 
如 果 一 个 模块 就 是 为 了 导出 特定 的 内 容 ， 那 么 你 应 该 考虑 使 用 一 个 默认 导出 。 
令 模 块 的 导入 和 使 用 变 得 些许 简单 。 比如 : 


MyClass.ts 


export default class SomeType { 
constructor O { i2.. } 


} 


MyFunc.ts 


export default function getThing() { return 'thing'; } 


Consumer.ts 


import t from "./MyClass"; 
import f from "./MyFunc"; 
let x = new t(); 
console.log(f()); 


对 用 户 来 说 这 是 最 理想 的 。 他 们 可 以 随意 命名 导入 模块 的 类 型 (ASIA t) EB. 
不 需要 多 余 的 〈.) 来 找到 相关 对 象 。 


如 果 要 导出 多 个 对 象 ， 把 它们 放 在 顶层 里 导出 
MyThings.ts 


export class SomeType { /* ... */ } 
export function someFunc() { /* ... */ } 


相反 地 ， 当 导入 的 时 候 : 


明确 地 列 出 导入 的 名 字 


Consumer.ts 


import { SomeType, SomeFunc } from "./MyThings"; 
let x = new SomeType(); 
let y = someFunc(); 


使 用 命名 空间 导入 模式 当 你 要 导出 大 量 内 容 的 时 候 
MyLargeModule.ts 


export class Dog { 上 
export, class Cat { 2.2 3 
export class Tree ( ... } 
export class Flower ( ... } 


Consumer.ts 


import * as myLargeModule from "./MyLargeModule.ts"; 
let x = new myLargeModule.Dog(); 


使 用 重新 导出 进行 扩展 


你 可 能 经 常 需要 去 扩展 一 个 模块 的 功能 。JS 里 常用 的 一 个 模式 是 JQuery 那 样 去 扩 
展 原 对 象 。 如 我 们 之 前 提 到 的 ， 模 块 不 会 像 全 局 命名 空间 对 象 那样 去 合并 。 推荐 
的 方案 是 不 要 去 改变 原来 的 对 象 ， 而 是 导出 一 个 新 的 实体 来 提供 新 的 功能 。 


假设 Calculator.ts 模块 里 定义 了 一 个 简单 的 计算 器 实现 。 这 个 模块 同样 提供 了 
一 个 辅助 函数 来 测试 计算 器 的 功能 ， 通 过 传 入 一 系列 输入 的 字符 串 并 在 最 后 给 出 结 
Xo 


Calculator.ts 


export class Calculator { 
private current = 0; 
private memory = 0; 
private operator: string; 


protected processDigit(digit: string, currentValue: number) 


{ 
if (digit >= "0" && digit <= "9") { 
return currentValue * 10 + (digit.charCodeAt(0) - "0" 
.charCodeAt(0)); 


} 


protected processOperator(operator: string) { 
if (["+", “-", "*", "/"]-indexof(operator) >= 9) { 
return operator; 


protected evaluateOperator(operator: string, left: number, r 
ight: number): number { 
switch (this.operator) { 
case "+": return left + right; 
case "-": return left - right; 
case "=": return left * right; 
case "/": return left / right; 


private evaluate() { 
if (this.operator) { 
this.memory = this.evaluateOperator(this.operator, t 
his.memory, this.current); 


j 
else ( 

this.memory - this.current; 
j 


this.current - 0; 


public handleChar(char: string) ( 
if (char === "=") { 
this.evaluate(); 
return; 


else { 
let value = this.processDigit(char, this.current); 


if (value !== undefined) { 
this.current = value; 
return; 
} 
else { 
let value = this.processOperator(char); 
if (value !== undefined) { 
this.evaluate(); 
this.operator - value; 
return; 
} 
} 


} 


throw new Error( Unsupported input: '$(char]'' ); 


public getResult() { 
return this.memory; 


export function test(c: Calculator, input: string) { 
for (let i = 0; i < input.length; i++) f 
c.handleChar(input[i]); 


console.log( result of '${input}' is '$(c.getResult())' ); 
} 


EE — o sj 
下 面 使 用 导出 的 test 元 数 来 测试 计算 器 。 


TestCalculator.ts 


import { Calculator, test } from "./Calculator"; 


let c = new Calculator(); 
test (c m 2 S31) 177 prints. 2 


现在 扩展 它 ， 添 加 支持 输入 其 它 进 制 (十 进 制 以 外 ) ， 让 我 们 来 创 


建 ProgrammerCalculator.ts ° 


ProgrammerCalculator.ts 


import { Calculator } from "./Calculator"; 


class ProgrammerCalculator extends Calculator { 
seis digits 二 ko is Hae 20 jocum E icu WEM, I Wow 
iio ee LANT MEN TEH UDI ME "E"T; 


constructor(public base: number) { 
super(); 
const maxBase - ProgrammerCalculator.digits.length; 
if (base <= 0 || base > maxBase) { 
throw new Error( base has to be within 0 to ${maxBas 
e) inclusive. `); 


j 
protected processDigit(digit: string, currentValue: number) 
if (ProgrammerCalculator.digits.indexOf(digit) >= 0) { 
return currentValue * this.base + ProgrammerCalculat 


or.digits.indexOf (digit); 
} 


// Export the new extended calculator as Calculator 
export { ProgrammerCalculator as Calculator }; 


// Also, export the helper function 
export { test } from "./Calculator"; 


新 的 ProgrammerCalculator 模块 导出 的 API 与 原先 的 Calculator 模块 很 相 
似 ， 但 却 没有 改变 原 模块 里 的 对 象 。 下 面 是 测试 ProgrammerCalculator 类 的 代码 : 


TestProgrammerCalculator.ts 


import { Calculator, test } from "./ProgrammerCalculator"; 


let c = new Calculator(2); 
test(c, "001+010="); 7 prints 3 


模块 里 不 要 使 用 命名 空间 


当初 次 进入 基于 模块 的 开发 模式 时 ， 可 能 总 会 控制 不 住 要 将 导出 包 衰 在 一 个 命名 空 
间 里 。 模块 具有 其 自己 的 作用 域 ， 并且 只 有 导出 的 声明 才 会 在 模块 外 部 可 见 。 记 
住 这 点 ， 命 名 空间 在 使 用 模块 时 几乎 没什么 价值 。 


在 组 织 方面 ， 命 名 空间 对 于 在 全 局 作用 域内 对 逻辑 上 相关 的 对 象 和 类 型 进行 分 组 是 
nies o e ， 在 C# 里 ， 你 会 从 System.Collections 里 找到 所 有 集合 的 类 


型 。 通 类 型 有 层次 地 组 织 在 命名 空 Loe ， 可 以 方便 用 户 找 到 与 使 用 那些 类 型 。 
然而 ， yey 已 经 存在 于 文件 系统 之 中 ， 这 是 必须 的 。 我 们 必须 通过 路 径 和 文件 


名 找到 它们 ， 这 已 经 提供 了 一 种 逻辑 上 的 eet 我 们 可 以 创 
建 /collections/generic/ 文件 夹 ， 把 相应 模块 放 在 这 里 面 。 


命名 空间 对 解决 全 局 作用 域 里 命名 冲突 来 说 是 很 重要 的 。 比如 ， 你 可 以 有 一 
个 My.Application.Customer.AddForm 和 My.Application.Order.AddForm - 
- 两 个 类 型 的 名 字 相 同 ， 但 命名 空间 不 同 。 然而 ， 这 对 于 模块 来 说 却 不 是 一 个 问 
题 。 在 一 个 模块 里 ， 没 有 理由 两 个 对 象 拥有 同一 个 名 字 。 从 模块 的 使 用 角度 来 
说 ， 使 用 者 会 挑 出 他 们 用 来 引用 模块 的 名 字 ， 所 以 也 没有 理由 发 生 重 名 的 情况 。 


更 多 关于 模块 和 命名 空间 的 资料 查看 命名 空间 和 模块 


危险 信号 


以 下 均 为 模块 结构 上 的 危险 信号 。 重 新 检查 以 确保 你 没有 在 对 模块 使 用 命名 空间 : 


e 文件 的 顶层 声明 是 export namespace Foo ( ... } (AIM Foo 并 把 所 有 
内 容 向 上 层 移 动 一 层 ) 

e 文件 只 有 一 个 export class 或 export function (考虑 使 用 export 
default ) 


e 多 个 文件 的 顶层 具有 同样 的 export namespace Foo { (不 要 以 为 这 些 会 合 
并 到 一 个 Foo 中 1!) 


模块 
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关于 术语 的 一 点 说 明 : 请 务必 注意 一 点 ，TypeScript 1.5 € 38 5 CLARET E 
化 。“ 内 部 模块 "现在 称 做 “命名 空间 *”。“ 外 部 模块 "现在 则 简称 为 “模块 "， 这 是 为 
了 与 ECMAScript 2015 里 的 术语 保持 一 致 ，( 也 就 是 说 module X { 相当 于 现 


在 推荐 的 写法 namespace X { )° 
介绍 
这 篇 文章 描述 了 如 何在 TypeScript 里 使 用 命名 空间 (之 前 叫做 “内 部 模块 ") 来 组 织 你 
的 代码 。 就 像 我 们 在 术语 说 明 里 提 到 的 那样 ，“ 内 部 模块 "现在 叫做 “命名 空间 ”。 S 


外 ， 任 何 使 用 module 关键 字 来 声明 一 个 内 部 模块 的 地 方 都 应 该 使 
用 namespace 关键 字 来 替换 。 这 就 避免 了 让 新 的 使 用 者 被 相似 的 名 称 所 迷惑 。 


第 一 步 


我 们 先 来 写 一 段 程序 并 将 在 整 篇 文章 中 都 使 用 这 个 例子 。 我 们 定义 几 个 简单 的 字符 
串 验 证 器 ， 假 设 你 会 使 用 它们 来 验证 表单 里 的 用 户 输 入 或 验证 外 部 数据 。 


所 有 的 验证 器 都 放 在 一 个 文件 里 


interface StringValidator { 
isAcceptable(s: string): boolean; 


let lettersRegexp = /A[A-Za-z]+$/; 
let numberRegexp = /^[0-9]-*$/; 


class LettersOnlyValidator implements StringValidator { 
isAcceptable(s: string) { 
return lettersRegexp.test(s); 


class ZipCodeValidator implements StringValidator ( 
isAcceptable(s: string) { 
return s.length === 5 && numberRegexp.test(s); 


// Some samples to try 
let strings = ["Hello", "98052", "101"]; 


// Nalidators to use 

let validators: { [s: string]: StringValidator; } = {}; 
validators["ZIP code"] = new ZipCodeValidator(); 
validators["Letters only"] - new LettersOnlyValidator(); 


// Show whether each string passed each validator 
for (let s of strings) ( 
for (let name in validators) ( 
let isMatch - validators[name].isAcceptable(s); 
console.log( '$( s }' $( isMatch ? "matches" : "does not 
match” } S4 name j'. ); 
J 


命名 空间 


随 着 更 多 验证 器 的 加 入 ， 我 们 需要 一 种 手段 来 组 织 代 码 ， 以 便于 在 记录 它们 类 型 的 
同时 还 不 用 担心 与 其 它 对 象 产 生命 名 冲突 。 因此 ， 我 们 把 验证 器 包 庄 到 一 个 命名 空 
间 内 ， 而 不 是 把 它们 放 在 全 局 命名 空间 下 。 


下 面 的 例子 里 ， 把 所 有 与 验证 器 相关 的 类 pM 做 validation 的 命名 
空间 里 。 因为 我 们 想 让 这 些 接口 和 类 在 命名 空间 之 外 也 是 可 访问 的 ， 所 以 需要 使 
用 export ° 相反 的 ， 变 量 lettersRegexp 和 numberRegexp 是 实现 的 细节 ， 
不 需要 导出 ， 因 此 它们 在 命名 空间 外 是 不 能 访问 的 。 在 文件 末尾 的 测试 代码 里 ， 由 
于 是 在 命名 空间 之 外 访问 ， 因 此 需要 限定 类 型 的 名 称 ， 比 

如 Validation.LettersOnlyValidator 。 


使 用 命名 空间 的 验证 器 


namespace Validation { 
export interface StringValidator { 
isAcceptable(s: string): boolean; 


const lettersRegexp = /A[A-Za-z]+$/; 
const numberRegexp = /A[0-9]+$/; 


export class LettersOnlyValidator implements StringValidator 


{ 
isAcceptable(s: string) { 
return lettersRegexp.test(s); 
} 
} 
export class ZipCodeValidator implements StringValidator { 
isAcceptable(s: string) { 
return s.length === 5 && numberRegexp.test(s); 
} 
} 
} 


// Some samples to try 
let strings = ["Hello", "98052", "101"]; 


// Validators to use 

let validators: ( [s: string]: Validation.StringValidator; } = { 
H 

validators["ZIP code"] = new Validation.ZipCodeValidator(); 
validators["Letters only"] - new Validation.LettersOnlyValidator 


©; 


// Show whether each string passed each validator 
for (let s of strings) { 
for (let name in validators) { 
console.log( "${ s }" - ${ validators[name].isAcceptable 
(s) ? "matches" : "does not match" } ${ name }`); 


} 


分 离 到 多 文件 
当 应 用 变 得 越 来 越 大 时 ， 我 们 需要 将 代码 分 离 到 不 同 的 文件 中 以 便于 维护 。 


多 文件 中 的 命名 空间 


现在 ， 我 们 把 Validation 命名 空间 分 割 成 多 个 文件 。 尽管 是 不 同 的 文件 ， 它 们 
仍 是 同一 个 命名 空间 ， 并 且 在 使 用 的 时 候 就 如 同 它们 在 一 个 文件 中 定义 的 一 样 。 
为 不 同文 件 之 间 存 在 依赖 关系 ， 所 以 我 们 加 入 了 引用 标签 来 告诉 编译 器 文件 之 间 的 
关联 。 我 们 的 测试 代码 保持 不 变 。 


Validation.ts 


namespace Validation { 
export interface StringValidator { 
isAcceptable(s: string): boolean; 


LettersOnlyValidator.ts 


/// «reference path="Validation.ts" /> 
namespace Validation { 
const lettersRegexp = /A[A-Za-z]+$/; 
export class LettersOnlyValidator implements StringValidator 


isAcceptable(s: string) { 
return lettersRegexp.test(s); 


ZipCodeValidator.ts 


/// «reference path="Validation.ts" /> 
namespace Validation { 
const numberRegexp = /A[0-9]+$/; 
export class ZipCodeValidator implements StringValidator { 
isAcceptable(s: string) { 
return s.length === 5 && numberRegexp.test(s); 


Test.ts 


/// «reference path="Validation.ts" /> 
/// «reference path="LettersOnlyValidator.ts" /> 
/// «reference path="ZipCodeValidator.ts" /> 


// Some samples to try 
let strings = ["Hello", "98052", "101"]; 


// Nalidators to use 
let validators: ( [s: string]: Validation.StringValidator; } = { 


3 
validators["ZIP code"] - new Validation.ZipCodeValidator(); 
validators["Letters only"] - new Validation.LettersOnlyValidator 


(); 


// Show whether each string passed each validator 
for (let s of strings) ( 
for (let name in validators) ( 
console.log( "${ s }" - $( validators[name].isAcceptable 
(s) ? "matches" : "does not match" } $( name ^); 


j 


当 涉 及 到 多 文件 时 ， 我 们 必须 确保 所 有 编译 后 的 代码 都 被 加 载 了 。 我们 有 两 种 方 
式 o 


第 一 种 方式 ， 把 所 有 的 输入 文件 编译 为 一 个 输出 文件 ， 需 要 使 用 --outFile 7% 
ee 


tsc --outFile sample.js Test.ts 


编译 器 会 根据 源码 里 的 引用 标签 自动 地 对 输出 进行 排序 。 你 也 可 以 单独 地 指定 每 个 
文件 。 


tsc --outFile sample.js Validation.ts LettersOnlyValidator.ts Zi 
pCodeValidator.ts Test.ts 


第 二 种 方式 ， 我 们 可 以 编译 每 一 个 文件 (默认 方式 ) ， 那 么 每 个 源 文 件 都 会 对 应 生 
成 一 个 JavaScript 文 件 。 然后， 在 页 面 上 通过 <script> 标签 把 所 有 生成 的 
JavaScript 文 件 按 正确 的 顺序 引进 来 ， 比 如 : 


MyTestPage.html (excerpt) 


<script src="Validation.js" type="text/javascript" /> 
<script src="LettersOnlyValidator.js" type="text/javascript" 


i= 
<script src="ZipCodeValidator.js" type="text/javascript" /> 


<script src="Test.js" type="text/javascript" /> 


别名 


另 一 种 简化 命名 空间 操作 的 方法 是 使 用 import q = x.y.z 给 常用 的 对 象 起 一 个 

短 的 名 字 。 不 要 与 用 来 加 载 模块 的 import x = require('name') 语法 再 混 了 ， 
这 里 的 语法 是 为 指定 的 符号 创建 一 个 别名 。 你 可 以 用 这 种 方法 为 任意 标识 符 创 建 别 
名 ， 也 包括 导入 的 模块 中 的 对 象 。 


namespace Shapes { 
export namespace Polygons { 
export class Triangle { } 
export class Square { } 


import polygons = Shapes.Polygons; 
let sq = new polygons.Square(); // Same as "new Shapes.Polygons. 


Square()" 


注意 ， 我 们 并 没有 使 用 require 关键 字 ， 而 是 直接 使 用 导入 符号 的 限定 名 赋值 。 
这 与 使 用 var 相似 ， 但 它 还 适用 于 类 型 和 导入 的 具有 命名 空间 含义 的 符号 。 重 要 
的 是 ， 对 于 值 来 讨 ， import 会 生成 与 原始 符号 不 同 的 引用 ， 所 以 改变 别名 

的 var 值 并 不 会 影响 原始 变量 的 值 。 


使 用 其 它 的 JavaScript 库 


为 了 描述 不 是 用 TypeScript 编 写 的 类 库 的 类 型 ， 我 们 需要 声明 类 库 寻 出 的 API 。 
于 大 部 分 程序 库 只 提供 少数 的 顶级 对 象 ， 命 名 空间 是 用 来 表示 ee E 


我 们 称 其 为 声明 是 因为 它 不 是 外 部 程序 的 具体 实现 。 我 们 通常 在 .d.ts 里 写 这 些 
声明 。 如 果 你 熟悉 C/C++， 你 可 以 把 它们 当做 .h 文件 。 让 我 们 看 一 些 例 子 。 


外 部 命名 空间 


流行 的 程序 库 D3 在 全 局 对 象 d3 里 定义 它 的 功能 。 因为 这 个 库 通过 一 

个 «script» 标签 加 载 (不 是 通过 模块 加 载 器 ) ， 它 的 声明 文件 使 用 内 部 模块 来 定 
义 它 的 类 型 。 为 了 让 TypeScript 编 译 器 识别 它 的 类 型 ， 我 们 使 用 外 部 命名 空间 声 

8] o 比如 ， 我 们 可 以 像 下 面 这 样 写 


D3.d.ts (部 分 摘录 ) 


declare namespace D3 { 
export interface Selectors { 
select: { 
(selector: string): Selection; 
(element: EventTarget): Selection; 


Ie 


export interface Event { 
x: number; 
y: number; 


export interface Base extends Selectors { 
event: Event; 


declare var d3: D3.Base; 


命名 空间 
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关于 术语 的 一 点 说 明 : 请 务必 注意 一 点 ，TypeScript 1.5 € REL CLARET E 
化 。“ 内 部 模块 "现在 称 做 “命名 空间 ”。"“ 外 部 模块 "现在 则 简称 为 “模块 "， 这 是 为 
1 1 2015 里 的 术语 保持 一 致 ，( 也 就 是 说 module x ( 相当 于 现 
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这 篇 文章 将 概括 介绍 在 TypeScript 里 使 用 模块 与 命名 空间 来 组 织 代码 的 方法 。 ^d 
也 会 谈 及 命名 空间 和 模块 的 高 级 使 用 场景 ， 和 在 使 用 它们 的 过 程 中 常见 的 陷 

查看 模块 章节 了 解 关于 模块 的 更 多 信息 。 查 看 命名 空间 章节 了 解 关于 命名 空间 的 更 
多 信息 。 


使 用 命名 空间 


间 是 位 于 全 局 命名 空 et ee di 这 令 命 

空间 十 分 容易 使 用 。 它们 可 以 在 多 文件 中 同时 使 用 ， 并 通过 --outFile 结合 在 

一 起 。 命名 空间 是 帮 你 组 织 Web 应 用 不 错 的 方式 ， i E 
R M4) «script» 标签 里 。 


但 就 像 其 它 的 全 局 命名 空间 污染 一 样 ， 它 很 难 去 识别 组 件 之 间 的 依赖 关系 ， 尤 其 是 
在 大 型 的 应 用 中 。 


使 用 模 : 


像 命名 空间 一 样 ， 模 块 可 以 包含 代码 和 声明 。 不 同 的 是 模块 可 以 声明 它 的 依赖 。 


模块 会 把 依赖 添加 到 模块 加 载 器 上 (例如 CommonJs / Require.js) » 对 于 小 型 的 
JS 应 用 来 说 可 能 没 必 要 ， 但 是 对 于 大 型 应 用 ， 这 一 点 点 的 花费 会 带 来 长 久 的 模块 化 
和 可 维护 性 上 的 便利 。 模块 也 提供 了 更 好 的 代码 重用 ， 更 强 的 封闭 性 以 及 更 好 的 使 
用 工具 进行 优化 。 


对 于 Node.js 应 用 来 说 ， 模 块 是 默认 并 推荐 的 组 织 代码 的 方式 。 


从 ECMAScript 2015 开 始 ， 模 块 成 为 了 语言 内 置 的 部 分 ， 应 该 会 被 所 有 正常 的 解释 
引擎 所 支持 。 因此 ， 对 于 新 项 目 来 说 推荐 使 用 模块 做 为 组 织 代码 的 方式 。 


命名 空间 和 模块 的 陷阱 


这 部 分 我 们 会 描述 常见 的 命名 空间 和 模块 的 使 用 陷阱 和 如 何 去 避 和 免 它们 。 


对 模块 使 用 /// «reference» 


一 个 常见 的 错误 是 使 用 /// «reference» 引用 模块 文件 ， 应 该 使 用 import ° 
要 理解 这 之 间 的 区 别 ， 我 们 首先 应 该 弄 清 编译 器 是 如 何 根据 import 路 径 (45 
如 ， import x from "..."; 或 import x = require("...") 里 面 的 ... ? 
等 等 ) 来 定位 模块 的 类 型 信息 的 。 


编译 器 首先 尝试 去 查找 相应 路 径 下 的 .ts > .tsx 再 或 者 .d.ts 。 如 果 这 些 广 
件 都 找 不 到 ， 编 译 器 会 查找 外 部 模块 声明 。 回想 一 下 ， 它 们 是 在 dits 文件 里 声 
明 的 。 


e myModules.d.ts 


// In a .d.ts file or .ts file that is not a module: 
declare module "SomeModule" { 
export function fn(): string; 


e myOtherModule.ts 


/// «reference path="myModules.d.ts" /> 
import * as m from "SomeModule"; 


这 里 的 引用 标签 指定 了 外 来 模块 的 位 置 。 这 就 是 一 些 TypeScript 例 子 中 引 
用 node.d.ts 的 方法 。 


不 必要 的 命名 空间 
如 果 你 想 把 命名 空间 转换 为 模块 ， 它 可 能 会 像 下 面 这 个 文件 一 件 : 


e shapes.ts 


export namespace Shapes { 
export class Triangle { /* ... *7 } 
export class Square { /* ... */ } 


顶层 的 模块 Shapes (X f Triangle 和 square 。 对 于 使 用 它 的 人 来 说 这 是 令 
人 迷惑 和 讨厌 的 : 


e shapeConsumer.ts 


import * as shapes from "./shapes"; 
let t = new shapes.Shapes.Triangle(); // shapes.Shapes? 


TypeScript 里 模块 的 一 个 特点 是 不 同 的 模块 永远 也 不 会 在 相同 的 作用 域内 使 用 相同 
的 名 字 。 因为 使 用 模块 的 人 会 为 它们 命名 ， 所 以 完全 没有 必要 把 导出 的 符号 包 衰 在 
一 个 命名 空间 里 。 


再 次 重申 ， 不 应 该 对 模块 使 用 命名 空间 ， 使 用 命名 空间 是 为 了 提供 逻辑 分 组 和 避免 
命名 冲突 。 模块 文件 本 身 已 经 是 一 个 逻辑 分 组 ， 并 且 它 的 名 字 是 由 导入 这 个 模块 的 
代码 指定 ， 所 以 没有 必要 为 导出 的 对 象 增 加 额外 的 模块 层 。 


下 面 是 改进 的 例子 : 


e shapes.ts 


export class Triangle { /* ... */ } 
export class Square { /* ... */ } 


e shapeConsumer.ts 


import * as shapes from "./shapes"; 
let t - new shapes.Triangle(); 


Bt RU NUS 


就 像 每 个 JS 文件 对 应 一 个 模块 一 样 ，TypeScript 里 模块 文件 与 生成 的 JS 文件 也 是 一 
一 对 应 的 。 这 会 产生 一 种 影响 ， 根 据 你 指定 的 目标 模块 系统 的 不 同 ， 你 可 能 无 法 连 
接 多 个 模块 源 文 件 。 例如 当 目 标 模块 系统 为 commonjs X umd 时 ， 无 法 使 

用 outFile 选项 ， 但 是 在 TypeScript 1.8 以 上 的 版 本 能 够 使 用 outFile 当 目 标 

为 amd 或 system ° 


这 节 假 设 你 已 经 了 解 了 模块 的 一 些 基本 知识 请 阅读 模块 文档 了 解 更 多 信息 。 


模块 解析 是 指 编译 器 在 查找 导入 模块 内 容 时 所 遵循 的 流程 。 人 假设 有 一 个 导入 语 
4] import { a } from "moduleA" ;为 了 去 检查 任何 对 a 的 使 用 ， 编 译 器 需 
准确 的 知道 它 表 示 什 么 ， 并 且 需 要 检查 它 的 定义 moduleA ° 


这 时 候 ， 编 译 器 会 有 个 疑问 “ moduleA 的 结构 是 怎样 的 ?” 这 听 上 去 很 简单 ， 
但 moduleA 可 能 在 你 写 的 某 个 ,ts / .tsx 文件 里 或 者 在 你 的 代码 所 依赖 
的 .d.ts 里 。 


首先 ， 编译 器 会 尝试 定位 表示 导入 模块 的 文件 。 编 译 器 会 遵循 以 下 二 种 策略 之 
— :Classic&Nodec 这 些 策略 会 告诉 编译 器 到 哪里 去 查找 moduleA 。 


如 果 上 面 的 解析 失败 了 并 且 模 块 名 是 非 相对 的 (HELE "moduleA" 的 情况 下 ) ， 
编译 器 会 党 试 定位 一 个 外 部 模块 声明 。 我 们 接 下 来 会 讲 到 非 相 对 导入 。 


最 后 ， 如 果 编 译 器 还 是 不 能 解析 这 个 模块 ， 它 会 记录 一 个 错误 。 在 这 种 情况 下 ， 错 
误 可 能 为 error TS2307: Cannot find module 'moduleA'. 


相对 vs. 非 相 对 模块 导入 


根据 模块 引用 是 相对 的 还 是 非 相 对 的 ， 模 块 导 入 会 以 不 同 的 方式 解析 。 
相对 导入 是 以 / ，./ 或 ,,/ 开头 的 。 下面 是 一 些 例子 : 


e import Entry from "./components/Entry"; 
e import { DefaultHeaders } from "../constants/http"; 


e import "/mod"; 
所 有 其 它 形式 的 导入 被 当 作 非 相对 的 。 下 面 是 一 些 例子 : 


e import * as $ from "jQuery"; 
e import ( Component } from "@angular/core"; 
相对 导入 在 解析 时 是 相对 于 导入 它 的 文件 ， 并 且 不 能 解析 为 一 个 外 部 模块 声明 。 你 
应 该 为 你 自己 写 的 模块 使 用 相对 导入 ， 这 样 能 确保 它们 在 运行 时 的 相对 位 置 。 
非 相对 模块 的 导入 可 以 相对 于 baseUrl 或 通过 下 文 会 讲 到 的 路 径 映 射 来 进行 解 
析 。 它们 还 可 以 被 解析 成 外 部 模块 声明 。 使 用 非 相 对 路 径 来 导入 你 的 外 部 依赖 。 


模块 解析 策略 


ee unc e 
moduleResolution 标记 来 指定 使 用 哪 种 模块 解析 策 若 未 指定 ， 那 么 在 使 用 
了 --module AMD | System | ES2015 apad tad 其 en 况 时 则 
7j Node 。 


Classic 


这 种 策略 在 以 前 是 TypeScript 默 认 的 解析 策略 。 现 在 ， 它 存在 的 理由 主要 是 为 了 向 
后 兼容 。 


相对 导入 的 模块 是 相对 于 导入 它 的 文件 进行 解析 的 。 
此 /root/src/folder/A.ts 文件 里 的 import { b } from "./moduleB" 会 使 
用 下 面 的 查找 流程 : 


1. /root/src/folder/moduleB.ts 
2. /root/src/folder/moduleB.d.ts 


对 于 非 相 对 模块 的 导入 ， 编 译 器 则 会 从 包含 导入 文件 的 目录 开始 依次 向 上 级 目录 遍 
历 ， 党 试 定位 匹配 的 声明 文件 。 


比如 : 


有 一 个 对 moduleB 的 非 相 对 导入 import { b } from "moduleB" ， 它 是 
在 /root/src/folder/A.ts 文件 里 ， 会 以 如 下 的 方式 来 定位 "modules" 


/root/src/folder/moduleB.ts 
/root/src/folder/moduleB.d.ts 
/root/src/moduleB.ts 
/root/src/moduleB.d.ts 
/root/moduleB.ts 
/root/moduleB.d.ts 
/moduleB.ts 

/moduleB.d.ts 


ONOO m e NE c 


Node 


这 个 解析 策略 试图 在 运行 时 模仿 Node.js 模 块 解析 机 制 。 完整 的 Node.js 解 析 算 法 可 
vA Æ Node.js module documentation 找 到 。 


Node.js 如 何 解析 模块 


为 了 理解 TypeScript 编 译 依 照 的 解析 步骤 ， 先 弄 明 白 Node.js 模 块 是 非常 重要 的 。 通 
常 ， 在 Node.js 里 导入 是 通过 require 函数 调用 进行 的 。 Node.js 会 根 
据 require 的 是 相对 路 径 还 是 非 相 对 路 径 做 出 不 同 的 行为 。 


相对 路 径 很 简单 。 例如 ， 假 设 有 一 个 文件 路 径 为 /root/src/moduleA.js ， 包 含 
了 一 个 导入 var x = require("./moduleB"); Node.js 以 下 面 的 顺序 解析 这 个 导 
A 


1. 检查 /root/src/moduleB.js 文件 是 否 存 在 。 


2. 检查 /root/src/moduleB 目录 是 否 包含 一 个 package.json 文件 ， 
E package.json 文件 指定 了 一 个 "main" 模块 。 在 我 们 的 例子 里 ， 如 果 
Node.js 发 现 文件 /root/src/moduleB/package.json 包含 了 { "main": 
"lib/mainModule.js" } ， 那 么 Node.js 会 引 
用 /root/src/moduleB/lib/mainModule.js 。 


3. 检查 /root/src/moduleB 目录 是 否 包含 一 个 index.js 文件 。 这 个 文件 会 
被 隐 式 地 当 作 那 个 文件 来 下 的 "main" 模 块 。 


你 可 以 阅读 Node.js 文 档 了 解 更 多 详细 信息 : file modules 和 folder modules ° 


， 非 相对 模块 名 的 解析 是 个 完全 不 同 的 过 程 。 Node 会 在 一 个 特殊 的 文件 
T node modules 里 查找 你 的 模块 。 node modules 可 能 与 当前 文件 在 同一 级 目 
录 下 ， 或 者 在 上 层 目录 里 。 Node 会 向 上 级 目录 遍历 ， 查 找 每 个 node_modules & 
到 它 找到 要 加 载 的 模块 。 


还 是 用 上 面 例子 ， 但 假设 /root/src/moduleA.js 里 使 用 的 是 非 相对 路 径 导 
A var x = require("moduleB"); ° Node 则 会 以 下 面 的 顺序 去 解 
析 moduleB ， 直 到 有 一 个 匹配 上 。 


1. /root/src/node modules/moduleB.js 
2. /root/src/node modules/moduleB/package.json (如 果 指 定 
了 "main" 属性 ) 


3. /root/src/node_modules/moduleB/index.js 


4. /root/node_modules/moduleB.js 
5. /root/node modules/moduleB/package.json (如 果 指 定 了 "main" 属性 ) 
6. /root/node modules/moduleB/index.js 


T. /node_modules/moduleB. js 
8. /node modules/moduleB/package.json (如 果 指 定 了 "main" 属性 ) 
9. /node modules/moduleB/index.js 


注意 Node.js 在 步骤 (4) 和 (7) 会 向 上 跳 一 级 目录 。 


你 可 以 阅读 Node.js 文 档 了 解 更 多 详细 信息 : loading modules from 


node modules ° 


TypeScript 如 何 解 析 模 块 


TypeScript 是 模仿 Node.js 运 行 时 的 解析 策略 来 在 编译 阶段 定位 模块 定义 文件 。 
此 ，TypeScript 在 Node 解 析 逻 辑 基 础 上 增加 了 TypeScript 源 文件 的 扩展 名 

( .ts > .tsx 和 .d.ts ) 。 同 时 ，TypeScript 在 package.json 里 使 用 字 
段 "types" 来 表示 类 似 "main" 的 意义 - 编译 器 会 使 用 它 来 找到 要 使 用 
的 "main" 定 义 文件 。 


比如 ， 有 一 个 导入 语句 import { b } from 
" /moduleB" 在 /root/src/moduleA.ts 里 ， 会 以 下 面 的 流程 来 定 
4L "./moduleB" 


1. /root/src/moduleB.ts 

2. /root/src/moduleB.tsx 

3. /root/src/moduleB.d.ts 

4. /root/src/moduleB/package.json (如 果 指 定 了 "types" 属性 ) 
5. /root/src/moduleB/index.ts 

6. /root/src/moduleB/index.tsx 

7 


/root/src/moduleB/index.d.ts 


回想 一 下 Node.js 先 查找 moduleB.js 文件 ， 然 后 是 合适 的 package.json ， 再 之 
后 是 index.js 。 


类 似 地 ， 非 相对 的 导入 会 遵循 Node.js 的 解析 逻辑 ， 首 先 查找 文件 ， 然 后 是 合适 的 文 
件 夹 。 因 此 /root/src/moduleA.ts 文件 里 的 import { b } from 
"moduleB" 会 以 下 面 的 查找 顺序 解析 : 


/root/src/node modules/moduleB.ts 
/root/src/node modules/moduleB.tsx 


/root/src/node modules/moduleB.d.ts 


Bop a 


/root/src/node modules/moduleB/package.json (如 果 指 定 
了 "types" 属性 ) 

5. /root/src/node_modules/moduleB/index.ts 

6. /root/src/node modules/moduleB/index.tsx 


T. /root/src/node modules/moduleB/index.d.ts 


8. /root/node modules/moduleB.ts 

9. /root/node modules/moduleB.tsx 

10. /root/node modules/moduleB.d.ts 

11. /root/node modules/moduleB/package.json (如 果 指 定 了 "types" Æ 
性 ) 

12. /root/node modules/moduleB/index.ts 

13. /root/node modules/moduleB/index.tsx 

14. /root/node modules/moduleB/index.d.ts 


15. /node modules/moduleB.ts 

16. /node modules/moduleB.tsx 

17. /node modules/moduleB.d.ts 

18. /node modules/moduleB/package.json (如 果 指 定 了 "types" 属性 ) 
19. /node modules/moduleB/index.ts 

20. /node modules/moduleB/index.tsx 

21. /node modules/moduleB/index.d.ts 


不 要 被 这 里 步骤 的 数量 吓 到 - TypeScript 只 是 在 步骤 (8) 和 (15) ALRT AXA 
录 。 这 并 不 比 Node.js 里 的 流程 复杂 。 


附加 的 模块 解析 标记 


有 时 工程 源码 结构 与 输出 结构 不 同 。 通常 是 要 经 过 一 系统 的 构建 步骤 最 后 生成 输 
出 。 它们 包括 将 ,ts 编译 成 .js ， 将 不 同位 置 的 依赖 拷贝 至 一 个 输出 位 置 。 最 
终结 果 就 是 运行 时 的 模块 名 与 包含 它们 声明 的 源 文件 里 的 模块 名 不 同 。 或 者 最 终 输 
出 文件 里 的 模块 路 径 与 编译 时 的 源 文件 路 径 不 同 了 。 


TypeScript 编 译 器 有 一 些 额 外 的 标记 用 来 通知 编译 器 在 源码 编译 成 最 终 输 出 的 过 
中 都 发 生 了 哪个 转换 。 


有 一 点 要 特别 注意 的 是 编译 器 不 会 进行 这 些 转换 操作 ; 它 只 是 利用 这 些 信息 来 指导 
模块 的 导入 。 


Base URL 


在 利用 AMD 模 块 加 载 器 的 应 用 里 使 用 baseUrl 是 常见 做 法 ， 它 要 求 在 运行 时 模块 
1 —— 。 这 些 模块 的 源码 可 以 在 不 同 的 目录 下 ， 但 是 构建 脚本 会 
将 它们 集中 到 一 起 。 


设置 baseUrl 来 告诉 编译 器 到 哪里 去 查找 模块 。 所 有 非 相 对 模块 导入 都 会 被 当做 
相对 于 baseUrl 。 


baseUr| 的 值 由 以 下 两 者 之 一 决定 : 


e 命令 行 中 baseUr/ 的 值 (如 果 给 定 的 路 径 是 相对 的 ， 那 么 将 相对 于 当前 路 径 进 
行 计算 ) 
e ‘tsconfig.json’ € 4) baseUrl BV (如 果 给 定 的 路 径 是 相对 的 ， 那 么 将 相对 
于 sconfig.json' 路 径 进行 计算 ) 
注意 相对 模块 的 导入 不 会 被 设置 的 baseurl 所 影响 ， 因 为 它们 总 是 相对 于 导入 它 
们 的 文件 。 


阅读 更 多 关于 baseurl 的 信息 RequireJS 和 SystemJS。 


路 径 映 射 


有 时 模块 不 是 直接 放 在 baseUn 下 面 。 比如， 充分 "jquery" 模块 地 导入 ， 在 运行 
时 可 能 被 解释 为 "node modules/jquery/dist/jquery.slim.min.js" ° 加 载 器 
使 用 映射 配置 来 将 模块 名 映射 到 运行 时 的 文件 ， 查 看 RequireJs documentation 和 
SystemJS documentation ° 


TypeScript 编 译 器 通过 使 用 tsconfig.json 文件 里 的 "paths" 来 支持 这 
明 映 射 。 AREE. jquery 的 "paths" 的 例子 。 


"compilerOptions": { 
"baseUrl": ".", // This must be specified if "paths" is. 
Datis c 
"jquery": ["node modules/jquery/dist/jquery"] // 此 处 映射 是 
相对 于 "baseUrl" 
} 


请 注意 "paths" 是 相对 于 "baseUrl" 进行 解析 。 如 果 "baseurl" 被 设置 成 了 


除 "." 外 的 其 它 值 ， 比如 tsconfig.json 所 在 的 目录 ， 那 么 映射 必须 要 做 相应 
的 改变 。 如 果 你 在 上 例 中 设置 了 "baseUrl": "./src" > AB Ajquery= HRA 


到 "../node modules/jquery/dist/jquery" ° 


通过 "paths" 我 们 还 可 以 指定 复杂 的 映射 ， 包 括 指 定 多 个 回 退 位 置 。 假设 在 一 个 
工程 配置 里 ， 有 一 些 模块 位 于 一 处 ， 而 其 它 的 则 在 另 个 的 位 置 。 构建 过 程 会 将 它们 
集中 至 一 处 。 工程 结构 可 能 如 下 : 


projectRoot 

I— folderi 

| — filei.ts (imports 'folderi/file2' and 'folder2/file3') 
| E puse 

I— generated 

| I— folderi 

| L— folder2 

| L— file3.ts 
L— tsconfig.json 


相应 的 tsconfig.json 文件 如 下 : 


"compilerOptions": { 


"baseüUrpLV* wv 
paths cr 
NES l 
sl fee 
"generated/*" 
] 


它 告 诉 编译 器 所 有 匹配 "*" (所 有 的 值 ) 模式 的 模块 导入 会 在 以 下 两 个 位 置 查 
找 : 


1. "*" : 表示 名 字 不 发 生 改 变 ， 所 以 映射 为 «moduleName» => 
<baseUrl>/<moduleName> 
2. "generated/*" 表示 模块 名 添加 了 “generated” 前 级 ， 所 以 映射 


为 «moduleName» => <baseUrl>/generated/<moduleName> 
按照 这 个 有 逻辑， 编译 器 将 会 如 下 尝试 解析 这 两 个 导入 : 


e 导入 'folder1/file2' 
1. 匹配 “模式 且 通 配 符 捕 获 到 整个 名 字 。 
2. 尝试 列表 里 的 第 一 个 替换 : -> folderi/file2 ° 
3. 替换 结果 为 非 相 对 名 - 与 baseUn 合 并 -> 
projectRoot/folderi/file2.ts ° 
4. 文件 存在 。 完 成 。 
e +A ‘folder2/file3' 
1. 匹配 “模式 且 通 配 符 捕 获 到 整个 名 字 。 
2. 尝试 列表 里 的 第 一 个 替换 : -> folder2/file3 。 
3. 替换 结果 为 非 相 对 名 - 与 baseUn 合 并 -> 
projectRoot/folder2/file3.ts ° 
文件 不 存在 ， 跳 到 第 二 个 替换 。 
5. 第 二 个 替换 : 'generated/* -> generated/folder2/file3 ° 
. 替换 结果 为 非 相 对 名 - 与 baseUn 合 并 -> 
projectRoot/generated/folder2/file3.ts ° 
7. 文件 存在 。 完 成 。 


小 


O 


利用 rootDirs 指定 虚拟 目录 


有 时 多 个 目录 下 的 工程 源 文件 在 编译 时 会 进行 合并 放 在 某 个 输出 目录 下 。 这 可 以 看 
做 一 些 源 目 录 创 建 了 一 个 “虚拟 "目录 。 


利用 rootDirs ， 可 以 告诉 编译 器 生成 这 个 虚拟 目录 的 roots ; 因此 编译 器 可 以 
在 “虚拟 "目录 下 解析 相对 模块 导入 ， 就 好 像 它们 被 合并 在 了 一 起 一 样 。 


比如 ， 有 下 面 的 工程 结构 : 


src 

L— views 
L— view1.ts (imports './templatei') 
L— view2.ts 


generated 
L— templates 
L— views 
L— templatei.ts (imports './view2') 


src/views 里 的 文件 是 用 于 控制 UI 的 用 户 代 码 。 generated/templates XUI 
版 ， 在 构建 时 通过 模版 生成 器 自动 生成 。 构建 中 的 一 步 会 
将 /src/views 和 /generated/templates/views 的 输出 拷贝 到 同一 个 目录 下 。 
在 运行 时 ， 视 图 可 以 假设 它 的 模版 与 它 同 在 一 个 目录 下 ， 因 此 可 以 使 用 相对 导 

A ",/template" ° 


可 以 使 用 "rootDirs" 来 告诉 编译 器 。  "rootDirs" 指定 了 一 个 roots 列 表 ， 列 表 
里 的 内 容 会 在 运行 时 被 合并 。 因此 ， 针 对 这 个 例子 ， tsconfig.json 如 下 : 


{ 
"compilerOptions": { 
"ootbITS :ol 
"src/views", 
"generated/templates/views" 
] 
} 


每 当 编 译 器 在 某 一 rootDirs 的 子 目 录 下 发 现 了 相对 模块 导入 ， 它 就 会 尝试 从 每 一 
个 rootDirs 中 导入 。 


rootDirs 的 灵活 性 不 仅仅 局 限于 其 指定 了 要 在 逻辑 上 合并 的 物理 目录 列表 。 它 提 
供 的 数组 可 以 包含 任意 数量 的 任何 名 字 的 目录 ， 不 论 它们 是 否 存 在 。 这 允许 编译 器 
以 类 型 安全 的 方式 处 理 复杂 捆绑 (bundles) 和 运行 时 的 特性 ， 比 如 条 件 引 入 和 工程 特 
定 的 加 载 器 插件 。 


设想 这 样 一 个 国际 化 的 场景 ， 构 建 工 具 自 动 插入 特定 的 路 径 记 号 来 生成 针对 不 同 区 

域 的 捆绑 ， 比 如 将 s(locale) 做 为 相对 模块 路 径 ./#{locale}/messages 的 一 
分 。 在 这 个 假定 的 设置 下 ， 工 具 会 枚 举 支持 的 区 域 ， 将 抽 像 的 路 径 映射 

成 ./zh/messages * ./de/messages 等 。 


假设 每 个 模块 都 会 导出 一 个 字符 串 的 数组 。 比 如 ./zh/messages 可 能 包含 : 


export default [ 
" 你 Ee " 
"很 高 兴 认识 你" 


1; 


利用 rootDirs 我 们 可 以 让 编译 器 了 解 这 个 映射 关系 ， 从 而 也 允许 编译 器 pe 
地 解析 ./#{locale}/messages ， 就 算 这 个 目录 永远 都 不 存在 。 比 如 ， 使 用 下 


的 tsconfig.json 


{ 

"compilerOptions": ( 
SroOEDIESP TI 
Monc/ zi 
"src/de", 

"src/#{locale}" 
] 
} 
} 


编译 器 现在 可 以 将 import messages from './#{locale}/messages' 解析 
为 import messages from './zh/messages' 用 做 工具 支持 的 目的 ， 并 人 允许 在 开 
发 时 不 必 了 解 区 域 信 息 。 


跟踪 模块 解析 


如 之 前 讨论 ， 编 译 器 在 解析 模块 时 可 能 访问 当前 文件 夹 外 的 文件 。 这 会 导致 很 难 诊 
断 模块 为 什么 没有 被 解析 ， 或 解析 到 了 错误 的 位 置 。 通 过 -- 

traceResolution 启用 编译 器 的 模块 解析 跟踪 ， 它 会 告诉 我 们 在 模块 解析 过 程 中 
发 生 了 什么 。 


假设 我 们 有 一 个 使 用 了 typescript 模块 的 简单 应 用 。 app,ts 里 有 一 个 这 样 的 


导入 import * as ts from "typescript" ° 


| tsconfig.json 

I—node modules 

| L—typescript 

| L—1ib 

| typescript.d.ts 
L—src 


app.ts 


yw 


使 用 --traceResolution 调用 编译 器 。 


tsc --traceResolution 


输出 结果 如 下 : 


Module resolution kind is not specified, using 'NodeJs'. 

Loading module 'typescript' from 'node_modules' folder. 

File 'src/node_modules/typescript.ts' does not exist. 

File 'src/node_modules/typescript.tsx' does not exist. 

File 'src/node_modules/typescript.d.ts' does not exist. 

File 'src/node_modules/typescript/package.json' does not exist. 
File 'node_modules/typescript.ts' does not exist. 

File 'node_modules/typescript.tsx' does not exist. 

File 'node_modules/typescript.d.ts' does not exist. 

Found 'package.json' at 'node_modules/typescript/package.json'. 
'package.json' has 'types' field './lib/typescript.d.ts' that re 
ferences 'node modules/typescript/lib/typescript.d.ts'. 

File 'node modules/typescript/lib/typescript.d.ts' exist - use i 
t as a module resolution result. 

-------- Module name 'typescript' was successfully resolved to ' 
node modules/typescript/lib/typescript.d.ts'. -------- 


需要 留意 的 地 方 


e 导入 的 名 字 及 位 置 


e 编译 器 使 用 的 策略 
Module resolution kind is not specified, using 'NodeJs". 
e 从 npm 加 载 types 


'package.json' has 'types' field './lib/typescript.d.ts' that references 
'node modules/typescript/lib/typescript.d.ts'. 


======== Module name 'typescript' was successfully resolved to 
'node modules/typescript/lib/typescript.d.ts'. ======== 


使 用 --noResolve 


正常 来 讲 编译 器 会 在 开始 编译 之 前 解析 模块 导入 。 每 当 它 成 功 地 解析 了 对 一 个 文 
TF import ， 这 个 文件 被 会 加 到 一 个 文件 列表 里 ， 以 供 编 译 器 稍 后 处 理 。 

--noResolve 编译 选项 告诉 编译 器 不 要 添加 任何 不 是 在 命令 行 上 传 入 的 文件 到 编 
译 列表 。 编译 器 仍然 会 尝试 解析 模块 ， 但 是 只 要 没有 指定 这 个 文件 ， 那 么 它 就 不 会 
被 包含 在 内 。 


比如 
app.ts 
import * as A from "moduleA" // OK, moduleA passed on the comman 


d-line 
import * as B from "moduleB" // Error TS2307: Cannot find module 





'moduleB'. 


tsc app.ts moduleA.ts --noResolve 


使 用 --noResolve 编译 app.ts 


e 可 能 正确 找到 moduleA ， 因 为 它 在 命令 行 上 指定 了 。 
e 找 不 到 moduleB ， 因 为 没有 在 命令 行 上 传递 。 


常见 问题 


为 什么 在 exclude 列表 里 的 模块 还 会 被 编译 器 使 用 


tsconfig.json 将 文件 夹 转变 一 个 "工程 ”如 果 不 指定 任 
fT “exclude” 或 “files”， 文 件 夹 里 的 所 有 文件 包括 tsconfig.json 和 所 有 
的 子 目录 都 会 在 编译 列表 里 。 如 果 你 想 利 用 “exclude” 排除 某 些 文件 ， 甚 至 你 想 
指定 所 有 要 编译 的 文件 列表 ， 请 使 用 "files" 。 

有 些 是 被 tsconfig.json 自动 加 入 的 。 它 不 会 涉及 到 上 面 讨论 的 模块 解析 。 如 
果 编 译 器 识别 出 一 个 文件 是 模块 导入 目标 ， 它 就 会 加 到 编译 列表 里 ， 不 管 它 是 否 被 
排除 了 。 


因此 ， 要 从 编译 列表 中 排除 一 个 文件 ， 你 需要 在 排除 它 的 同时 ， 还 要 排除 所 有 对 它 
进行 import 或 使 用 了 /// <reference path="..." /> 指令 的 文件 。 


TypeScript 中 有 些 独特 的 概念 可 以 在 类 型 层面 上 描述 JavaScript 对 象 的 模型 。 这 其 
中 尤其 独特 的 一 个 例子 是 “声明 合并 "的 概念 。 理 解 了 这 个 概念 ， 将 有 助 于 操作 现 有 
的 JavaScript 代 码 。 同时 ， 也 会 有 助 于 理解 更 多 高 级 抽象 的 概念 。 


对 本 文件 来 讲 ， “声明 合并 "是 指 编译 器 将 针对 同一 个 名 字 的 两 个 独立 声明 合并 为 单 
一 声明 。 合并 后 的 声明 同时 拥有 原先 两 个 声明 的 特性 。 任何 数量 的 声明 都 可 被 合 
并 ; 不 局 限于 两 个 声明 。 


基础 概念 


TypeScript 中 的 声明 会 创建 以 下 三 种 实体 之 一 : 命名 空间 ， 类 型 或 值 。 创 建 命名 空 
间 的 声明 会 新 建 一 个 命名 空间 ， 它 包含 了 用 (.) 符号 来 访问 时 使 用 的 名 字 。 创建 
类 型 的 声明 是 : 用 声明 的 模型 创建 一 个 类 型 并 绑 定 到 给 定 的 名 字 上 。 最 后 ， 创 建 值 
的 声明 会 创建 在 JavaScript 输 出 中 看 到 的 值 。 


Declaration Type Namespace Type Value 
Namespace X X 
Class X X 
Enum X X 
Interface X 
Type Alias X 
Function X 
Variable X 


滑 


解 每 个 声明 创建 了 什么 ， 有 助 于 理解 当 声 明 合并 时 有 哪些 东西 被 合并 了 。 


合并 接口 


最 简单 也 最 常见 的 声明 合并 类 型 是 接口 合并 。 从 根本 上 说 ， 合 并 的 机 制 是 把 双方 的 
成 员 放 到 一 个 同名 的 接口 里 。 


interface Box { 
height: number; 
width: number; 


interface Box { 
scale: number; 


let box: Box = (height: 5, width: 6, scale: 10}; 


4i a 83 3E BAA MR ELTAGCUE— o 如 果 它 们 不 是 唯一 的 ， 那 么 它们 必须 是 相同 的 
类 型 。 如 果 两 个 接口 中 同时 声明 了 同名 的 非 函 数 成 员 且 它们 的 类 型 不 同 ， 则 编译 器 
会 报错 。 

对 于 函数 成 员 ， 每 个 同名 函数 声明 都 会 被 当成 这 个 函数 的 一 个 重 塌 。 同 时 需要 注 
意 ， 当 接口 A 与 后 来 的 接口 A 合并 时 ， 后 面 的 接口 具有 更 高 的 优先 级 。 


如 下 例 所 示 : 


interface Cloner { 
clone(animal: Animal): Animal; 


interface Cloner { 
clone(animal: Sheep): Sheep; 


interface Cloner ( 
clone(animal: Dog): Dog; 
clone(animal: Cat): Cat; 


这 三 个 接口 合并 成 一 个 声明 : 


interface Cloner { 
clone(animal: Dog): Dog; 
clone(animal: Cat): Cat; 
clone(animal: Sheep): Sheep; 
clone(animal: Animal): Animal; 


注意 每 组 接口 里 的 声明 顺序 保持 不 变 ， 但 各 组 接口 之 间 的 顺序 是 后 来 的 接口 重 载 出 
现在 靠 前 位 置 。 


这 个 规则 有 一 个 例外 是 当 出 现 特殊 的 函数 签名 时 。 如 果 签 名 里 有 一 个 参数 的 类 型 是 
单一 的 字符 串 字面 量 (比如 ， 不 是 字符 串 字 面 量 的 联合 类 型 ) ， 那 么 它 将 会 被 提升 
到 重 载 列表 的 最 顶端 。 


比如 ， 下 面 的 接口 会 合并 到 一 起 : 


interface Document { 
createElement(tagName: any): Element; 

} 

interface Document { 
createElement(tagName: "div"): HTMLDivElement; 
createElement(tagName: "span"): HTMLSpanElement; 

} 

interface Document { 
createElement(tagName: string): HTMLElement; 
createElement(tagName: "canvas"): HTMLCanvasElement; 


合并 后 的 Document 将 会 像 下 面 这 样 : 


interface Document { 
createElement(tagName: "canvas"): HTMLCanvasElement; 
createElement(tagName: "div"): HTMLDivElement; 
createElement(tagName: "span"): HTMLSpanElement; 
createElement(tagName: string): HTMLElement; 
createElement(tagName: any): Element; 


合并 命名 空间 


 . ds 空间 也 会 合并 其 成 员 。 命 名 空间 会 创建 出 命名 空间 和 值 ， 
我 们 需要 知道 这 两 者 都 是 怎么 合并 的 。 


对 于 命名 空间 的 合并 ， 模 块 导出 的 同名 接口 进行 合并 ， 构 成 单一 命名 空间 内 含 合并 
eg 
对 于 命名 空间 里 值 的 合并 ， 如 果 当 前 已 经 存在 给 定名 字 的 命名 空间 ， 那 么 后 来 的 命 


名 空间 的 导出 成 员 会 被 加 到 已 经 存在 的 那个 模块 里 。 


Animals 声明 合并 示例 : 


namespace Animals { 
export class Zebra { } 


namespace Animals { 
export interface Legged { numberOfLegs: number; } 
export class Dog { } 


FATF: 


namespace Animals { 
export interface Legged { numberOfLegs: number; } 


export class Zebra { } 
export class Dog { } 


除了 合并 外 ， 你 还 需要 了 解 非 导 出 成 员 是 如 何 处 理 的 。 非 导出 成 员 仅 在 其 原 有 
o 空间 内 可 见 。 这 就 是 说 合并 之 后 ， 从 其 它 命名 空间 合并 进来 的 
成 员 无 法 访问 非 导 出 成 员 。 


下 例 提供 了 更 清晰 的 说 明 : 


namespace Animal { 
let haveMuscles = true; 


export function animalsHaveMuscles() { 
return haveMuscles; 


namespace Animal { 
export function doAnimalsHaveMuscles() { 
return haveMuscles; // <-- error, haveMuscles is not vi 
sible here 


} 


因为 haveMuscles 并 没有 导出 ， 只 有 animalsHaveMuscles 函数 共享 了 原始 未 
合并 的 命名 空间 可 以 访问 这 个 变量 。 doAnimalsHaveMuscles 前 数 虽 是 合并 命名 
空间 的 一 部 分 ， 但 是 访问 不 了 未 导出 的 成 员 。 


命名 空间 与 类 和 函数 和 枚 举 类 型 合并 


命名 空间 可 以 与 其 它 类 型 的 声明 进行 合并 。 只 要 命名 空间 的 定义 符合 将 要 合并 类 型 
的 定义 。 合 并 结果 包含 两 者 的 声明 类 型 。 TypeScript 使 用 这 个 功能 去 实现 一 些 
JavaScript 里 的 设计 模式 。 


合并 命名 空间 和 类 
这 让 我 们 可 以 表示 内 部 类 。 


class Album { 
label: Album.AlbumLabel; 
} 
namespace Album { 
export class AlbumLabel { } 


合并 规则 与 上 面 合并 命名 空间 小 节 里 讲 的 规则 一 致 ， 我 们 必须 导 
出 AlbumLabel 类 ， 好 让 合并 的 类 能 访问 。 合并 结果 是 一 个 类 并 带 有 一 个 内 部 
Ko 你 也 可 以 使 用 命名 空间 为 类 增加 一 些 静 态 属 性 。 


除了 内 部 类 的 模式 ， 你 在 JavaScript 里 ， 创 建 一 个 函数 稍 后 扩展 它 增 加 一 些 属性 也 
是 很 常见 的 。TypeScript 使 用 声明 合并 来 达到 这 个 目的 并 保证 类 型 安全 。 


function buildLabel(name: string): string { 
return buildLabel.prefix + name + buildLabel.suffix; 


namespace buildLabel { 
export let suffix = ""; 
export let prefix - "Hello, "; 


, 


alert(buildLabel("Sam Smith")); 


相似 的 ， 命 名 空间 可 以 用 来 扩展 枚 举 型 : 


enum Color { 


red = 1, 
green = 2, 
blue = 4 


namespace Color { 
export function mixColor(colorName: string) { 
if (colorName == "yellow") { 
return Color.red + Color.green; 


} 
else if (colorName == "white") { 
return Color.red + Color.green + Color.blue; 
} 
else if (colorName == "magenta") { 
return Color.red + Color.blue; 
J 
else if (colorName -- "cyan") ( 
return Color.green + Color.blue; 
} 


非法 的 合并 


TypeScript 并 非 允 许 所 有 的 合并 。 目前 ， 类 不 能 与 其 它 类 或 变量 合并 。 MET He 
何 模仿 类 的 合并 ， 请 参考 TypeScript 的 混入 。 


模块 扩展 


虽然 JavaScript 不 支持 合并 ， 但 你 可 以 为 导入 的 对 象 打 补丁 以 更 新 它们 。 让 我 们 考 
察 一 下 这 个 玩具 性 的 示例 : 


// observable.js 
export class Observable<T> { 
// ... implementation left as an exercise for the reader 


// map.js 

import { Observable } from "./observable"; 

Observable.prototype.map = function (f) { 
// ... another exercise for the reader 


它 也 可 以 很 好 地 工作 在 TypeScript 中 ， 但 编译 器 对 
Observable.prototype.map 一 无 所 知 。 你 可 以 使 用 扩展 模块 来 将 它 告诉 编译 


// observable.ts stays the same 
// map.ts 
import { Observable } from "./observable"; 
declare module "./observable" { 
interface Observable<T> { 
map<U>(f: (x: T) => U): Observable<U>; 


} 
Observable.prototype.map = function (f) { 
// ... another exercise for the reader 


// consumer.ts 

import ( Observable ) from "./observable"; 
import "./map"; 

let o: Observable<number>; 

o.map(x -» x.toFixed()); 


模块 名 的 解析 和 用 import / export 解析 模块 标识 符 的 方式 是 一 致 的 。 更 多 信息 
请 参考 Modules。 当 这 些 声 明 在 扩展 中 合并 时 ， 就 好 像 在 原始 位 置 被 声明 了 一 样 。 
但 是 ， 你 不 能 在 扩展 中 声明 新 的 顶级 声明 一 仅 可 以 扩展 模块 中 已 经 存在 的 声明 o 


全 局 扩展 
你 也 以 在 模块 内 部 添加 声明 到 全 局 作用 域 中 。 
// observable.ts 


export class Observable<T> { 
// ... Still no implementation ... 


declare global ( 
interface Array<T> { 
toObservable(): Observable<T>; 


Array.prototype.toObservable = function () { 
RD 


全 局 扩展 与 模块 扩展 的 行为 和 限制 是 相同 的 。 


3 5 .d.tsx fF 


本 页 面 被 移动 到 书写 声明 文件 页 
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SSX 2 — FRE A 85 RALXML 6538 Ko 它 可 以 被 转换 成 合法 的 JavaScript， 尽 管 转 
换 的 语义 是 依据 不 同 的 实现 而 定 的 。 JSX 因 React 框 架 而 流行 ， 但 也 存在 其 它 的 实 
现 。TypeScript 支 持 内 获 ， 类 型 检查 以 及 将 JSX 直 接 编译 为 JavaScript 。 


基本 用 法 


想 要 使 用 JSX 必 须 做 两 件 事 : 


1. 给 文件 一 个 .tsx 扩展 名 
2. 启用 jsx 选项 


TypeScript 具 有 三 种 JSX 模 式 : preserve ， react 和 react-native 。 这 些 模 
式 只 在 代码 生成 阶段 起 作用 - 类 型 检查 并 不 受 影 响 。 在 preserve 模式 下 生成 代 
码 中 会 保留 JSX 以 供 后 续 的 转换 操作 使 用 《比如 : Babel) 。 另外 ， 输 出 文件 会 带 
有 .jsx 扩展 名 。 react 模式 会 生成 React.createElement ， 在 使 用 前 不 需 
要 再 进行 转换 操作 了 ， 输 出 文件 的 扩展 名 为 ,js ° react-native 相当 

于 preserve ， 它 也 保留 了 所 有 的 JSX， 但 是 输出 文件 的 扩展 名 是 .js ° 


— 
模式 输入 输出 kv 
preserve poe «div /» . jsx 
react red React.createElement("div") .js 
react- <div : : 
native /? Hiis «dS 


你 可 以 通过 在 命令 行 里 使 用 --jsx 标记 或 tsconfig.json 里 的 选项 来 指定 模式 。 


注意 : React 标识 符 是 写 死 的 硬 编 码 ， 所 以 你 必须 保证 React (大 写 的 尺 ) 是 
可 用 的 。 


as 操作 符 


var foo = <foo>bar; 


这 里 断言 bar 变量 是 foo 类 型 的 。 因为 TypeScript 也 使 用 尖 括 号 来 表示 类 型 断 


言 ， 在 结合 JSX 的 语法 后 将 带 来 解析 上 的 困难 。 因 此 ，TypeScript 在 .tsx 文件 里 
禁用 了 使 用 尖 括 号 的 类 型 断言 。 


由 于 不 能 够 在 ,tsx 文件 里 使 用 上 述 语法 ， 因 此 我 们 应 该 使 用 另 一 个 类 型 断言 操作 
符 : as 。 上 面 的 例子 可 以 很 容易 地 使 用 as HRAS : 


var foo = bar as foo; 


as 操作 符 在 .ts 和 .tsx 里 都 可 用 ， 并 且 与 尖 括 号 类 型 断言 行为 是 等 价 的 。 


类 型 检查 

为 了 理解 JSX 的 类 型 检查 ， 你 必须 首先 理解 固有 元 素 与 基于 值 的 元 素 之 间 的 区 别 。 
假设 有 这 样 一 个 JSX 表 达 式 <expr /> > expr 可 能 引用 环境 自 带 的 某 些 东西 (上 比 
如 ， 在 DOM 环 境 里 的 div 或 span ) 或 者 是 你 自 定义 的 组 件 。 这 是 非常 重要 


的 ， 原 因 有 如 下 两 点 : 

1. 对 于 React， 固 有 元 素 会 生成 字符 串 ( React.createElement("div") ) ， 
然而 由 你 自 定义 的 组 件 却 不 会 生成 
( React.createElement(MyComponent) ) ° 


2. 传 入 JSX 元 素 里 的 属性 类 型 的 查找 方式 不 同 。 固有 元 素 属性 本 身 就 支持 ， 然 而 


自 定 义 的 组 件 会 自己 去 指定 它们 具有 哪个 属性 。 


TypeScript 使 用 与 React 相 同 的 规范 来 区 别 它们 。 固有 元 素 总 是 以 一 个 小 写字 母 开 
头 ， 基 于 值 的 元 素 总 是 以 一 个 大 写字 母 开头 。 


有 元 素 

国有 元 素 使 用 特殊 的 接口 JSX.IntrinsicElements 来 查找 。 默认 地 ， 如 果 这 个 
接口 没有 指定 ， 会 全 部 通过 ， 不 对 固有 元 素 进行 类 型 检查 。 然而 ， 如 果 这 个 接口 存 
在 ， 那 么 国有 元 素 的 名 字 需 要 在 JSX.IntrinsicElements 接口 的 属性 里 查找 。 


例如 : 


declare namespace JSX ( 
interface IntrinsicElements { 
foo: any 


«foo /»; // 正确 
«bar /»; // 错误 


在 上 例 中 ， «foo /> 没有 问题 ， 但 是 «bar /> SRB? AACA 
在 JSX.IntrinsicElements 里 指定 。 


注意 : 你 也 可 以 在 Jsx.IntrinsicElements 上 指定 一 个 用 来 捕获 所 有 字符 串 
dg 
AN J 


declare namespace JSX { 
interface IntrinsicElements { 
[elemName: string]: any; 


基于 值 的 元 素 会 简单 的 在 它 所 在 的 作用 域 里 按 标识 符 查 找 。 


import MyComponent from "./myComponent"; 


«MyComponent />; // 正确 
<SomeOtherComponent /»; // 错误 
有 两 种 方式 可 以 定义 基于 值 的 元 素 : 


1. 无 状态 函数 组 件 (SFC) 
2. 类 组 件 


由 于 这 两 种 基于 值 的 元 素 在 JSX 表 达 式 里 无 法 区 分 ， 因 此 TypeScript 首 先 会 党 试 将 
表达 式 做 为 无 状态 函数 组 件 进行 解析 。 如 果 解 析 成 功 ， 那 么 TypeScript 就 完成 了 表 
达 式 到 其 声明 的 解析 操作 。 如 果 按 照 无 状态 函数 组 件 解析 失败 ， 那 么 TypeScript 会 
继续 尝试 以 类 组 件 的 形式 进行 解析 。 如 果 依 旧 失 败 ， 那 么 将 输出 一 个 错误 。 


无 状态 函数 组 件 


正如 其 名 ， 组 件 被 定义 成 JavaScript 函 数 ， 它 的 第 一 个 参数 是 props 对 象 。 
TypeScript 会 强制 它 的 返回 值 可 以 赋值 给 JSX.Element ° 


interface FooProp { 
name: string; 
X: number; 
Y: number; 


declare function AnotherComponent(prop: {name: string}); 
function ComponentFoo(prop: FooProp) { 
return <AnotherComponent name=prop.name />; 


const Button = (prop: (value: string}, context: { color: string 
}) => <button> 


由 于 无 状态 函数 组 件 是 简单 的 JavaScript 骂 数 ， 所 以 我 们 还 可 以 利用 函数 重 载 。 


interface ClickableProps { 
children: JSX.Element[] | JSX.Element 


interface HomeProps extends ClickableProps { 
home: JSX.Element; 


interface SideProps extends ClickableProps { 
side: JSX.Element | string; 


function MainButton(prop: HomeProps): JSX.Element; 
function MainButton(prop: SideProps): JSX.Element ( 


类 组 件 


我 们 可 以 定义 类 组 件 的 类 型 。 然而 ， 我 们 首先 最 好 弄 懂 两 个 新 的 术语 : 元 素 类 的 类 
型 和 元 素 实例 的 类 型 。 


现在 有 «Expr /> ， 元 素 类 的 类 型 为 Expr 的 类 型 。 所 以 在 上 面 的 例子 里 ， 如 
Æ MyComponent 是 ES6 的 类 ， 那 么 类 类 型 就 是 类 的 构造 函数 和 静态 部 分 。 如 
Æ MyComponent 是 个 工厂 函数 ， 类 类 型 为 这 个 函数 。 


一 旦 建立 起 了 类 类 型 ， 实 例 类 型 由 类 构造 器 或 调用 签名 (如 果 存 在 的 话 ) 的 返回 值 
的 联合 构成 。 再 次 说 明 ， 在 ES6 类 的 情况 下 ， 实 例 类 型 为 这 个 类 的 实例 的 类 型 ， 并 
且 如 果 是 工厂 函数 ， 实 例 类 型 为 这 个 函数 返回 值 类 型 。 


class MyComponent { 
render() {} 


// 使 用 构造 签名 
var myComponent = new MyComponent(); 


// 元 素 类 的 类 型 => MyComponent 
// 元 素 实例 的 类 型 => { render: () => void } 


function MyFactoryFunction() { 
return { 
render: () => { 


} 


// 使 用 调用 签名 
var myComponent = MyFactoryFunction(); 


// 元 素 类 的 类 型 => FactoryFunction 
元 素 实 例 的 类 型 => { render: () => void } 


元 素 的 实例 类 型 很 有 趣 ， 因 为 它 必 须 赋值 给 JSX.Elementclass 或 抛 出 一 个 错 
o 默认 的 JSX.ElementClass 为 {} ， 但 是 它 可 以 被 扩展 用 来 限制 JSX 的 类 型 
以 符合 相应 的 接口 。 


declare namespace JSX ( 
interface ElementClass ( 
render: any; 


class MyComponent { 
render() {} 
} 


function MyFactoryFunction() { 
return { render: () => {} } 


«MyComponent />; // 正确 
«MyFactoryFunction />; // 正确 


class NotAValidComponent {} 
function NotAValidFactoryFunction() { 
return {}; 


«NotAValidComponent /»; // 错误 
«NotAValidFactoryFunction /»; // 错误 


属性 类 型 检查 


属性 类 型 检查 的 第 一 步 是 确定 元 素 属性 类 型 。 这 在 固有 元 素 和 基于 值 的 元 素 之 间 稍 
有 不 同 。 


对 于 固有 元 素 ， 这 是 JSX.IntrinsicElements 属性 的 类 型 。 


declare namespace JSX ( 
interface IntrinsicElements { 
foo: ( bar?: boolean } 


// foo 的 元 素 属 性 类 型 为 ` (bar?: boolean]? 
<foo bar />; 


对 于 基于 值 的 元 素 ， 就 稍微 复杂 些 。 它 取决 于 先前 确定 的 在 元 素 实 例 类 型 上 的 某 个 
属性 的 类 型 。 至 于 该 使 用 哪个 属性 来 确定 类 型 取决 

于 JsX.ElementAttributesProperty ° 它 应 该 使 用 单一 的 属性 来 定义 。 这 个 属 
性 名 之 后 会 被 使 用 。 TypeScript 2.8， 如 果 未 指 

X JSX.ElementAttributesProperty ， 那 么 将 使 用 类 元 素 构 造 吕 数 或 SFC 调 用 
的 第 一 个 参数 的 类 型 。 


declare namespace JSX ( 
interface ElementAttributesProperty { 
props; // 指定 用 来 使 用 的 属性 名 


class MyComponent { 
// 在 元 素 实例 类 型 上 指定 属性 


props: { 
foo?: string; 


// “MyComponent ` 的 元 素 属性 类 型 为 `{foo?: string) 
«MyComponent foo="bar" /> 


元 素 属 性 类 型 用 于 的 JSX 里 进行 属性 的 类 型 检查 。 支持 可 选 属性 和 必须 属性 。 


declare namespace JSX ( 
interface IntrinsicElements { 
foo: { requiredProp: string; optionalProp?: number } 


«foo requiredProp="bar" /»; // 正确 

«foo requiredProp="bar" optionalProp={0} /»; // 正确 

«foo /»; // 错误 ， 缺 少 requiredProp 

«foo requiredProp={0} />; // 4&i&, requiredProp 应 该 是 字符 囊 

«foo requiredProp="bar" unknownProp />; // 4&i&, unknownProp 不 存在 


«foo requiredProp="bar" some-unknown-prop />; // 正确 ， ~some-unkn 
own-prop 不 是 个 合法 的 标识 符 


图 TI Rl 


注意 : 如 果 一 个 属性 名 不 是 个 合法 的 JS 标识 符 〈 像 data-* A) ， 并 且 它 没 
出 现在 元 素 属性 类 型 里 时 不 会 当做 一 个 错误 。 


另外 ，JSX 还 会 使 用 Jsx.IntrinsicAttributes 接口 来 指定 额外 的 属性 ， 这 些 额 
外 的 属性 通常 不 会 被 组 件 的 props 或 arguments 使 用 - 比如 React 里 的 key 。 还 

Æ > JSX.IntrinsicClassAttributes<T> 泛 型 类 型 也 可 以 用 来 做 同样 的 事情 。 
这 里 的 泛 型 参数 表示 类 实例 类 型 。 在 React 里 ， 它 用 来 允许 Ref<T> 类 型 上 

的 ref 属性 。 通 常 来 讲 ， 这 些 接口 上 的 所 有 属性 都 是 可 选 的 ， 除 非 你 想 要 用 户 在 
每 个 JSX 标 签 上 都 提供 一 些 属性 。 


延展 操作 符 也 可 以 使 用 : 


var props = { requiredProp: 'bar' }; 
«foo {...props} />; // 正确 


var badProps = {}; 
«foo {...badProps} />; // 错误 


子孙 类 型 检查 


从 TypeScript 2.37248 > 1151 A children& X KE » children% zo X % tE 

(attribute) 3& # &*j — 4- 44 9&.& TE (property) > -FJSXExpression?t 4 3& 46 A 9| E T£ V. » 

与 使 用 JSXx.ElementAttributesProperty 来 决定 props 名 类 似 ， 我 们 可 以 利 

用 JSX.ElementChildrenAttribute 来 决定 children 名 。 
JSX.ElementChildrenAttribute 应 该 被 声明 在 单一 的 属性 (property) 里 。 


declare namespace JSX ( 
interface ElementChildrenAttribute { 
children: {}; // specify children name to use 


如 不 特殊 指定 子孙 的 类 型 ， 我 们 将 使 用 React typings 里 的 默认 类 型 。 


<div> 
<hi>Hello</h1i> 


</div>; 


<div> 
<hi>Hello</h1> 
World 

</div>; 


const CustomComp = (props) => <div>props.children</div> 
<CustomComp> 

<div>Hello World</div> 

{"This is just a JS expression..." + 1000} 
</CustomComp> 


interface PropsType { 
children: JSX.Element 
name: string 


class Component extends React.Component«PropsType, (j^ { 
render() { 
return ( 
«h2» 
{this.props.children} 
</h2> 


// OK 
<Component> 

<hi>Hello World</h1> 
</Component> 


// Error: children is of type JSX.Element not array of JSX.Eleme 
nt 
<Component> 
<hi>Hello World</h1> 
<h2>Hello World</h2> 
</Component> 


// Error: children is of type JSX.Element not array of JSX.Eleme 
nt or string. 
<Component> 
<hi>Hello</h1i> 
World 
</Component> 
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JSX 结 采 关 型 


默认 地 JSX 表 达 式 结果 的 类 型 为 any 。 你 可 以 自 定 义 这 个 类 型 ， 通 过 指 
X JSX.Element 接口 。 然 而 ， 不 能 够 从 接口 里 检索 元 素 ， 属 性 或 JSX 的 子 元 素 的 
类 型 信息 。 它 是 一 个 黑 盒 。 


RABY RIA 式 
JSX 人 允许 你 使 用 { } HARNRRARK © 


var a = <div> 
{['foo', 'bar'].map(i => <span>{i / 2}</span>)} 
</div> 


上 面 的 代码 产生 一 个 错误 ， 因 为 你 不 能 用 数字 来 除 以 一 个 字符 串 。 输 出 如 下 ， 若 你 
使 用 了 preserve 选项 : 


var a = <div> 
{['foo', 'bar'].map(function (i) { return <span>{i / 2}</span> 
; })} 


</div> 


React € 


要 想 一 起 使 用 JSX 和 React， 你 应 该 使 用 React 类 型 定义 。 这些 类 型 声明 定义 
1 Jsx 合适 命名 空间 来 使 用 React 。 


/// «reference path="react.d.ts" /> 


interface Props { 
foo: string; 


class MyComponent extends React.Component<Props, {}> { 
render() { 
return <span>{this.props.foo}</span> 


<MyComponent foo="bar" />; // 正确 
«MyComponent foo={0} />; // 错误 


ILJ ax 


jsx: react 编译 选项 使 用 的 工厂 函数 是 可 以 配置 的 。 可 以 使 用 jsxFactory 4 
令 行 选项 ， 或 内 联 的 @jsx 注释 指令 在 每 个 文件 上 设置 。 比 如 ， 

给 createElement 设置 jsxFactory ， </div> 会 使 

用 createElement("div") 来 生成 ， 而 不 是 React.createElement("div") ° 


注释 指令 可 以 像 下 面 这 样 使 用 (在 TypeScript 2.8 © ) 
import preact = require("preact"); 


/* @jsx preact.h */ 
const x = </div>; 


生成 : 


const preact = require("preact"); 
const x = preact.h("div", null); 


函数 的 选择 同样 会 影响 JSX 命名 空间 的 查找 (类 型 检查 ) ode LJ HAE 
m React.createElement 定义 (Ki) ， 编 译 器 会 先 检 查 React.JSX ， 之 后 才 
检查 全 局 的 JSX 。 如 果 工 厂 函 数 定义 为 h ， 那 么 在 检查 全 局 的 JSX 之 前 先 检 


4 h.JSX 


随 着 TypeScript 和 ES6 里 引入 了 类 ， 在 一 些 场景 下 我 们 需要 额外 的 特性 来 支持 标注 
或 修改 类 及 其 成 员 。 装饰 器 (Decorators) 为 我 们 在 类 的 声明 及 成 员 上 通过 元 编程 
语法 添加 标注 提供 了 一 种 方式 。 Javascript 里 的 装饰 器 目前 处 在 建议 征集 的 第 二 阶 
段 ， 但 在 TypeScript 里 已 做 为 一 项 实验 性 特性 予以 支持 。 

注意 装饰 器 是 一 项 实验 性 特性 ， 在 未 来 的 版 本 中 可 能 会 发 生 改 变 。 


若 要 局 用 实验 性 的 装饰 器 特性 ， 你 必须 在 命令 行 或 tsconfig.json 里 局 


用 experimentalDecorators 编译 器 选项 : 
命令 行 


tsc --target ES5 --experimentalDecorators 


tsconfig.json: 


{ 
"compilerOptions": { 
"target": "ES5", 
"experimentalDecorators": true 
} 
} 


J+ gg 
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装饰 器 是 一 种 特殊 类 型 的 声明 ， 它 能 够 被 附加 到 类 声明 ， 方 法 ， 访 问 符 ， 属 性 或 参 
数 上 。 装饰 器 使 用 @expression 这 种 形式 ， expression 求 值 后 必须 为 一 个 函 
数 ， 它 会 在 运行 时 被 调用 ， 被 装饰 的 声明 信息 做 为 参数 传 入 。 


例如 ， 有 一 个 Qsealed 装饰 器 ， 我 们 会 这 样 定 义 sealed HA: 


function sealed(target) { 
// do something with "target" 


注意 ”后面 类 装饰 器 小 节 里 有 一 个 更 加 详细 的 例子 


定制 一 个 修饰 器 如 何 应 用 到 一 个 声明 上 ， 我 们 得 写 一 个 装饰 器 工厂 


装饰 器 工厂 就 是 一 个 简单 的 函数 ， 它 返回 一 个 表达 


我 们 可 以 通过 下 面 的 方式 来 写 一 个 装饰 器 工厂 函数 : 


function color(value: string) ( // za- 


return function (target) ( // 3X XX^ 
// do something with "target" and 


注意 ”下 面 方法 装饰 器 小 节 里 有 一 个 更 加 详细 的 例子 


式 ， 以 供 装 饰 器 在 运行 


EMEEN 


"yalue"... 


当 多 个 装饰 器 应 用 于 一 个 声明 上 ， 它 们 求 值 方式 与 复合 函数 相似 。 在 这 个 模型 下 ， 
3 E Sffeght > ¥ S42 (f » g)(x)# HT figo) » 


同样 的 ， 在 TypeScript 里 ， 当 多 个 装饰 器 应 用 在 一 个 声明 上 时 会 进行 如 下 步骤 的 操 
作 : 


1. 由 上 至 下 依次 对 装饰 器 表达 式 求 值 。 
2. 求 值 的 结果 会 被 当 作 函数 ， 由 下 至 上 依次 调用 。 


如 果 我 们 使 用 装饰 器 工厂 的 话 ， 可 以 通过 下 面 的 例子 来 观察 它们 求 值 的 顺序 : 


function f() { 
console.log("f(): evaluated"); 
return function (target, propertyKey: string, descriptor: Pr 
opertyDescriptor) { 
console.log("f(): called"); 


function g() T 
console.log("g(): evaluated"); 
return function (target, propertyKey: string, descriptor: Pr 
opertyDescriptor) { 
console. log("g(): called"); 


J 
} 
class C { 
Qf () 
@g() 
method() {} 
} 


在 控制 台 里 会 打印 出 如 下 结果 : 


f(): evaluated 
g(): evaluated 
g(): called 
f(): called 


A+ g E 

装饰 器 来 值 

类 中 不 同 声明 上 的 装饰 器 将 按 以 下 规定 的 顺序 应 用 : 

1. 参数 装饰 器 ， 然 后 依次 是 方法 装饰 器 ， 访 问 符 装 饰 器 ， 或 属性 装饰 器 应 用 到 每 
个 实例 成 员 。 

2. 参数 装饰 器 ， 然 后 依次 是 方法 装饰 器 ， 访 问 符 装 饰 器 ， 或 属性 装饰 器 应 用 到 每 
个 静态 成 员 。 

3. 参数 装饰 器 应 用 到 构造 函数 。 

4. 类 装饰 器 应 用 到 类 。 


类 装饰 器 在 类 声明 之 前 被 声明 o 类 装饰 器 应 用 于 类 构造 函数 ， 可 
以 用 来 监视 ， 修 改 或 替换 类 定义 。 类 装饰 器 不 能 用 在 声明 文件 中 ( .d.ts )， 也 不 
能 用 在 任何 外 部 上 下 文中 (比如 declare his o 
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如 果 类 装饰 器 返回 一 个 值 ， 它 会 使 用 提供 的 构造 函数 来 蔡 换 类 的 声明 。 


注意 如 果 你 要 返回 一 个 新 的 构造 函数 ， 你 必须 注意 处 理 好 原来 的 原型 链 。 在 
P. 
} 
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下 面 是 使 用 类 装饰 器 ( @sealed ) 的 例子 ， 应 用 在 Greeter X: 


@sealed 
class Greeter { 
greeting: string; 
constructor(message: string) { 
this.greeting = message; 


} 
greet() { 

return "Hello, " + this.greeting; 
} 


我 们 可 以 这 样 定义 @sealed 装饰 器 : 


function sealed(constructor: Function) { 
Object.seal(constructor); 
Object.seal(constructor.prototype); 


3 @sealed 被 执行 的 时 候 ， 它 将 密封 此 类 的 构造 函数 和 原型 。( 注 : 参见 
Object.seal) 


下 面 是 一 个 重 载 构造 函数 的 例子 。 
function classDecorator<T extends {new(...args:any[]):{}}>(const 


rüuctor*T) € 
return class extends constructor { 


newProperty = "new property"; 
hello = "override"; 
} 
} 
@classDecorator 


class Greeter { 
property = "property"; 
hello: string; 
constructor(m: string) { 
this.hello = m; 


console.log(new Greeter("world")); 


Y GR 2 


方法 装饰 器 声明 在 一 个 方法 的 声明 之 前 〈 紧 靠 着 方法 声明 ) 。 它 会 被 应 用 到 方法 的 
属性 描述 符 上 ， 可 以 用 来 监视 ， 修 改 或 者 替换 方法 定义 。 方法 装饰 器 不 能 用 在 声明 
文件 ( .d.ts )， 重 载 或 者 任何 外 部 上 下 文 (比如 declare 的 类 ) 中 


o 


RR BARA RST Be RAGIN IL» AFIT BAL: 
1 对 于 静态 成 员 来 说 是 类 的 构造 函数 ， 对 于 实例 成 员 是 类 的 原型 对 象 。 


2. 成 员 的 名 字 。 
3. 成 员 的 属性 描述 符 。 


注意 ”如果 代码 输出 目标 版 本 小 于 ES5 ， 属 性 描述 符 将 会 是 undefined -° 
如 果 方 法 装饰 器 返回 一 个 值 ， 它 会 被 用 作 方 法 的 属性 描述 符 。 

注意 ”如 果 代 码 输 出 目标 版 本 小 于 ESS 返回 值 会 被 忽略 。 
下 面 是 一 个 方法 装饰 器 〈 @enumerable ) 的 例子 ， 应 用 于 Greeter 类 的 方法 


E: 


class Greeter { 
greeting: string; 
constructor (message: string) { 
this.greeting = message; 


} 
@enumerable(false) 
greet() { 
return "Hello, " + this.greeting; 
} 


我 们 可 以 用 下 面 的 函数 声明 来 定义 @enumerable 装饰 器 : 


function enumerable(value: boolean) { 
return function (target: any, propertyKey: string, descripto 
r: PropertyDescriptor) ( 
descriptor.enumerable - value; 


}; 


这 里 的 @enumerable(false) 是 一 个 装饰 器 工厂 。 当 装饰 


eu 


器 Qenumerable(false) 被 调用 时 ， 它 会 修改 属性 描述 符 的 enumerable 属性 。 


访问 器 装饰 器 声明 在 一 个 访问 器 的 声明 之 前 〈 紧 靠 着 访问 器 声明 ) 。 访问 器 装饰 器 

应 edd. 问 器 的 属性 描述 符 并 且 可 以 用 来 监视 ， 修 改 或 蔡 换 一 个 访问 器 的 定义 。 3 
器 装饰 器 不 能 用 在 声明 文件 中 (dts) ， 或 者 任何 外 部 上 下 文 〈 比 

. declare 的 类 ) 里 


注意 “TypeScript 不 允许 同时 装饰 一 个 成 员 的 get fe set 访问 器 。 取而代之 
的 是 ， 一 个 成 员 的 所 有 装饰 的 必须 应 用 在 文档 顺序 的 第 一 个 访问 器 上 。 这 是 因 
为 ， 在 装饰 器 应 用 于 一 个 属性 描述 符 时 ， 它 联合 了 get 和 set 访问 器 ， 而 不 
是 分 开 声 明 的 。 


地 


访问 器 装饰 器 表达 式 会 在 运行 时 当 作 函数 被 调用 ， 传 入 下 列 3 个 参数 : 


1， 对 于 静态 成 员 来 说 是 类 的 构造 函数 ， 对 于 实例 成 员 是 类 的 原型 对 蔓 。 
2. 成 员 的 名 字 。 
3. 成 员 的 属性 描述 符 。 


注意 ”如果 代码 输出 目标 版 本 小 于 ES5 ，Property Descriptor 将 会 
是 undefined ° 

如 果 访 问 器 装饰 器 返回 一 个 值 ， 它 会 被 用 作 方 法 的 属性 描述 符 。 
注意 ”如 果 代 码 输出 目标 版 本 小 于 ESS 返回 值 会 被 忽略 。 


下 面 是 使 用 了 访问 器 装饰 器 ( @configurable ) 的 例子 ， 应 用 于 Point 类 的 成 
nE: 


class Point { 
private _x: number; 


private _y: number; 
constructor(x: number, y: number) { 


thas; eS x 
this._y = y; 

} 

@configurable( false) 


get x() { return this._x; } 


@configurable( false) 
get y() { return this._y; } 


az 


RATT VAG de F BAP ARE L @configurable 装饰 器 : 


function configurable(value: boolean) { 
return function (target: any, propertyKey: string, descripto 
r: PropertyDescriptor) { 
descriptor.configurable = value; 


Hh 


属性 装饰 器 


属性 装饰 器 声明 在 一 个 属性 声明 之 前 ( 紧 靠 着 属性 声明 ) 。 属 性 装饰 器 不 能 用 在 
明文 件 中 (dts) ， 或 者 任何 外 部 上 下 文 (比如 declare 的 类 ) € 


属性 装饰 器 表达 式 会 在 运行 时 当 作 函数 被 调用 ， 传 入 下 列 2 个 参数 : 


1. 对 于 着 


达 
态 成 员 来 说 是 类 的 构造 函数 ， 对 于 实例 成 员 是 类 的 原型 对 象 。 
2. 成 员 的 名 字 


o 


注意 ”属性 描述 符 不 会 做 为 参数 传 入 属性 装饰 器 ， 这 与 TypeScript 是 如 何 初 始 
化 属性 装饰 器 的 有 关 。 因为 目前 没有 办 法 在 定义 一 个 原型 对 象 的 成 员 时 描述 一 
个 实例 属性 ， 并 且 没 办 法 监视 或 修改 一 个 属性 的 初始 化 方法 。 返 回 值 也 会 被 忽 
mo 因此 ， 属 性 描述 符 只 能 用 来 监视 类 中 是 否 声 明了 某 个 名 字 的 属性 。 


如 果 访问 符 装饰 器 返回 一 个 值 ， 它 会 被 用 作 方法 的 属性 描述 符 。 


我 们 可 以 用 它 来 记录 这 个 属性 的 元 数据 ， 如 下 例 所 示 : 


class Greeter { 
@format("Hello, %s") 
greeting: string; 


constructor(message: string) { 
this.greeting = message; 


} 
greet() { 
let formatString = getFormat(this, "greeting"); 
return formatString.replace("%s", this.greeting); 
} 


iz 


然后 定义 Qformat X th AA getFormat BA: 
import "reflect-metadata"; 
const formatMetadataKey = Symbol("format"); 


function format(formatString: string) ( 
return Reflect.metadata(formatMetadataKey, formatString); 


function getFormat(target: any, propertyKey: string) { 

return Reflect.getMetadata(formatMetadataKey, target, proper 
tyKey); 
} 


这 个 Qformat("Hello, %s") 装饰 器 是 个 KML e 3 @format("Hello, 
%s") 被 调用 时 ， 它 添加 一 条 这 个 属性 的 元 数据 ， 通 过 reflect-metadata /& € 
的 Reflect.metadata 函数 。 当 getFormat 被 调用 时 ， 它 读 取 格式 的 元 数据 。 


注意 ”这 个 例子 需要 使 用 reflect-metadata È ° 查看 元 数据 了 
解 reflect-metadata 库 更 详细 的 信息 。 


参数 装饰 


N 
as 


ee nU ce 
造 函 数 或 方法 声明 。 参 数 装饰 器 不 能 用 在 声明 文件 (dts) ， 重 载 或 其 它 外 部 上 下 
X (比如 declare HR) 里 


参数 装饰 器 表达 式 会 在 运行 时 当 作 函 数 被 调用 ， 传 入 下 列 3 个 参数 : 
1、 对 于 静态 成 员 来 说 是 类 的 构造 函数 ， 对 于 实例 成 员 是 类 的 原型 对 象 。 
2. 成 员 的 名 字 。 

3. 参数 在 函数 参数 列表 中 的 索引 。 


注意 ”参数 装饰 器 只 能 用 来 监视 一 个 方法 的 参数 是 否 被 传 入 。 


class Greeter { 
greeting: string; 


constructor(message: string) { 
this.greeting = message; 


@validate 
greet(@required name: string) ( 
return "Hello " + name + ", " + this.greeting; 
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后 我 们 使 用 下 面 的 函数 定义 @required 和 @validate 装饰 器 : 


import "reflect-metadata"; 
const requiredMetadataKey = Symbol("required"); 


function required(target: Object, propertyKey: string | symbol, 
parameterIndex: number) { 
let existingRequiredParameters: number[] = Reflect.getOwnMet 
adata(requiredMetadatakey, target, propertyKey) || []; 
existingRequiredParameters.push(parameterIndex); 
Reflect.defineMetadata(requiredMetadataKey, existingRequired 
Parameters, target, propertyKey); 
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function validate(target: any, propertyName: string, descriptor: 
TypedPropertyDescriptor<Function>) ( 
let method - descriptor.value; 
descriptor.value - function () ( 
let requiredParameters: number[] = Reflect.getOwnMetadat 
a(requiredMetadataKey, target, propertyName); 
if (requiredParameters) ( 
for (let parameterIndex of requiredParameters) { 
if (parameterIndex »- arguments.length || argume 
nts[parameterIndex] --- undefined) ( 
throw new Error("Missing required argument." 


); 


return method.apply(this, arguments); 


@required 装饰 器 添加 了 元 数据 实体 把 参数 标记 为 必需 的 。 @validate 装饰 器 
把 greet 方法 包 计 在 一 个 函数 里 在 调用 原先 的 函数 前 验证 函数 参数 。 


注意 ”这 个 例子 使 用 了 reflect-metadata 库 。 查看 元 数据 了 解 reflect- 
metadata 库 的 更 多 信息 。 


元 数据 


一 些 例子 使 用 了 reflect-metadata 库 来 支持 实验 性 的 metadata API。 这 个 库 还 
WO tt a 。 然而 ， 当 装饰 器 被 ECMAScript 官 方 
标准 采纳 后 ， 这 些 扩展 也 将 被 推荐 给 ECMAScript 以 采纳 。 


你 可 以 通过 npm 安 装 这 个 库 : 


npm i reflect-metadata --save 


TypeScript 支 持 为 带 有 装饰 器 的 声明 生成 元 数据 。 你 需要 在 命 


命令 行 
或 tsconfig.json 里 启用 emitDecoratorMetadata 编译 器 选项 。 


Command Line: 


tsc --target ES5 --experimentalDecorators --emitDecoratorMetadat 
a 


tsconfig.json: 


{ 
"compilerOptions": { 
teamget 21 Ess, 
"experimentalDecorators": true, 
"emitDecoratorMetadata": true 
} 
} 


当 尼 用 后 ， 只 要 reflect-metadata 库 被 引入 了 ， 设 计 阶 段 添加 的 类 型 信息 可 以 
在 运行 时 使 用 。 


如 下 例 所 示 : 


import "reflect-metadata"; 


class Point { 
x: number; 
y: number; 


class Line { 
private pO: Point; 
private _p1: Point; 


Qvalidate 

set pO(value: Point) ( this. pO - value; ) 
get po() { return this. pO; } 

Qvalidate 

set pi(value: Point) ( this. p1 = value; } 


get pi() { return this. pi; } 


function validate<T>(target: any, propertyKey: string, descripto 
r: TypedPropertyDescriptor<T>) { 
let set = descriptor.set; 
descriptor.set = function (value: T) { 
let type = Reflect.getMetadata("design:type", target, pr 
opertyKey); 
if (!(value instanceof type)) (1 
throw new TypeError("Invalid type."); 
} 


set(value); 


T, 


TypeScript 编 译 器 可 以 通过 @Reflect.metadata 装饰 器 注入 设计 阶段 的 类 型 信 
息 。 你 可 以 认为 它 相 当 于 下 面 的 TypeScript : 


class Line { 
private pO: Point; 
private _p1: Point; 


@validate 

@Reflect.metadata("design:type", Point) 
set pO(value: Point) ( this. pO = value; } 
get po() { return this. pO; } 


@validate 

@Reflect.metadata("design:type", Point) 
set pi(value: Point) ( this. p1 = value; } 
get pi() { return this. p1; } 


注意 ”装饰 器 元 数据 是 个 实验 性 的 特性 并 且 可 能 在 以 后 的 版 本 中 发 生 破坏 性 的 
改变 (breaking changes) e 


ANAND 


除了 传统 的 面向 对 象 继 承 方 式 ， 还 流行 一 种 通过 可 重用 组 件 创建 类 的 方式 ， 就 是 联 
合 另 一 个 简单 类 的 代码 。 你 可 能 在 Scala 等 语言 里 对 mixins 及 其 特性 已 经 很 熟悉 
了 ， 但 它 在 JavaScript 中 也 是 很 流行 的 。 


混入 示例 


下 面 的 代码 演示 了 如 何在 TypeScript 里 使 用 混入 。 后面 我 们 还 会 解释 这 段 代码 是 怎 
么 工作 的 。 


// Disposable Mixin 
class Disposable { 
isDisposed: boolean; 
dispose() { 
this.isDisposed = true; 


// Activatable Mixin 
class Activatable { 
isActive: boolean; 
activate() { 
this.isActive = true; 
} 
deactivate() { 
this.isActive = false; 


class SmartObject implements Disposable, Activatable { 
constructor() { 
setInterval(() => console.log(this.isActive + " : " + th 
is.isDisposed), 500); 
} 


interact() { 
this.activate(); 


// Disposable 

isDisposed: boolean = false; 
dispose: () => void; 

// Activatable 

isActive: boolean = false; 
activate: () => void; 
deactivate: () => void; 


} 
applyMixins(SmartObject, [Disposable, Activatable]); 


let smartObj = new SmartObject(); 
setTimeout(() => smartObj.interact(), 1090); 


EDN DLO GEIS GATE SG ASS GWM GN GGT 
// In your runtime library somewhere 
人 


function applyMixins(derivedCtor: any, baseCtors: any[]) { 
baseCtors.forEach(baseCtor => { 
Object.getOwnPropertyNames(baseCtor.prototype).forEach(n 
ame => { 
derivedCtor.prototype[name] = baseCtor.prototype[nam 


理解 这 个 例子 


代码 里 首先 定义 了 两 个 类 ， 它 们 将 做 为 mixins。 可 以 看 到 每 个 类 都 只 定义 了 一 个 特 
定 的 行为 或 功能 。 稍 后 我 们 使 用 它们 来 创建 一 个 新 类 ， 同 时 具有 这 两 种 功能 。 


// Disposable Mixin 
class Disposable { 
isDisposed: boolean; 
dispose() { 
this.isDisposed = true; 


// Activatable Mixin 
class Activatable { 
isActive: boolean; 
activate() { 
this.isActive = true; 


} 


deactivate() { 
this.isActive = false; 


下 面 创 建 一 个 类 ， 结 合 了 这 两 个 mixins。 下 面 来 看 一 下 具体 是 怎么 操作 的 : 


class SmartObject implements Disposable, Activatable { 


KARRERA” A A SCC 78 Anplenoriss o 把 类 当成 了 接 
口 ， 仅 使 用 Disposable 和 Activatable 的 类 型 而 非 其 实现 。 这 意味 着 我 们 需要 在 类 里 
面 实现 接口 。 但 是 这 是 我 们 在 用 mixin 时 想 避 免 的 。 


我 们 可 以 这 么 做 来 达到 目的 ， BONNER quu ln 这 告 
诉 编译 器 这 些 成 员 在 运行 时 是 可 用 的 。 这 样 就 能 使 用 mixin 带 来 的 便利 ， 虽 说 需要 
提前 定义 一 些 占 位 属性 。 


// Disposable 

isDisposed: boolean = false; 
dispose: () => void; 

// Activatable 

isActive: boolean = false; 
activate: () => void; 
deactivate: () => void; 


applyMixins(SmartObject, [Disposable, Activatable]); 


最 后 ， 创 建 这 个 帮助 函数 ， 帮 我 们 做 混入 操作 。 它 会 遍历 mixins 上 的 所 有 属性 ， 并 
复制 到 目标 上 去 ， 把 之 前 的 占 位 属性 替换 成 站 正 的 实现 代码 。 


function applyMixins(derivedCtor: any, baseCtors: any[]) { 
baseCtors.forEach(baseCtor => { 
Object.getOwnPropertyNames(baseCtor.prototype).forEach(n 
ame => { 
derivedCtor.prototype[name] = baseCtor.prototype[nam 


三 斜 线 指 令 是 包含 单个 XML 标签 的 单行 注释 。 注释 的 内 容 会 做 为 编译 器 指令 使 用 。 


a bi 令 仅 可 放 在 包含 它 的 文件 的 最 顶端 。 一 个 三 斜 线 指令 的 前 面 只 能 出 现 单行 
行 注 释 ， 这 包括 其 它 的 三 斜 线 指 令 。 如 果 它 们 出 现在 一 个 语 匈 或 声明 之 后 ， 那 
它们 会 被 当做 普通 的 单行 注释 ， 并 且 不 具有 特殊 的 涵义 。 


/// <reference path="..." /> 

/// «reference pathz"..." /> 指令 是 三 针线 指令 中 最 常见 的 一 种 。 它 用 于 声 
明文 件 间 的 依赖 。 
三 斜 线 引 用 告诉 编译 器 在 编译 过 程 中 要 引入 的 额外 的 文件 。 


当 使 用 --out X --outFile 时 ， 它 也 可 以 做 为 调整 输出 内 容 顺序 的 一 种 方法 。 
文件 在 输出 文件 内 容 中 的 位 置 与 经 过 预 处理 后 的 输入 顺序 一 致 。 


预 处 理 输入 文件 
编译 器 会 对 输入 文件 进行 预 处理 来 解 术 所 有 三 斜 线 引 用 指令 。 在 这 个 过 程 中 ， 额 外 
的 文件 会 加 到 编译 过 程 中 。 


这 个 过 程 会 以 一 些 根 文件 开始 ; 它们 是 在 命令 行 中 指定 的 文件 或 是 

在 tsconfig.json 中 的 "files" 列表 里 的 文件 。 这 些 根 文件 按 指 定 的 顺序 进行 
预 处 理 。 在 一 个 文件 被 加 入 列表 前 ， 它 包含 的 所 有 三 斜 线 引用 都 要 被 处 理 ， 还 有 它 
们 包含 的 目标 。 三 斜 线 引用 以 它们 在 文件 里 出 现 的 顺序 ， 使 用 深度 优先 的 方式 解 
析 。 


一 个 三 斜 线 引用 路 径 是 相对 于 包含 它 的 文件 的 ， 如 果 不 是 根 文件 。 


引用 不 存在 的 文件 会 报错 。 一 个 文件 用 三 斜 线 指令 引用 自己 会 报错 。 


使 用 --noResolve 


如 果 指 定 了 --noResolve 编译 选项 ， 三 斜 线 引用 会 被 忽略 ; 它们 不 会 增加 新 文 
件 ， 也 不 会 改变 给 定 文件 的 顺序 。 


/// <reference types="..." /> 


与 /// «reference pathz"..." /> 指令 相似 ， 这 个 指令 是 用 来 声明 依赖 的 ; 
个 /// «reference types="..." /> 指令 则 声明 了 对 某 个 包 的 依赖 。 


对 这 些 包 的 名 字 的 解析 与 在 import 语句 里 对 模块 名 的 解析 类 似 。 可 以 简单 地 把 
三 针线 类 型 引用 指令 当做 import 声明 的 包 


例如 ， 把 /// «reference types="node" /> 引入 到 声明 ae ， 表明 这 个 文件 使 
用 了 EA A d.ts 里 面 声明 的 名 字 ; 并 且 ， 包 需 要 在 编译 阶段 
与 声明 文件 一 起 被 包含 进来 。 


仅 当 在 你 需要 写 一 个 d.ts 文件 时 才 使 用 这 个 指令 。 


对 于 那些 在 编译 阶段 生成 的 声明 文件 ， 编 译 器 会 自动 地 添加 /// «reference 
typesz"..." /> ; 当 且 仅 当 结果 文件 中 使 用 了 引用 的 包 里 的 声明 时 才 会 在 生成 的 
声明 文件 里 添加 /// «reference types="..." /> 14 » 


BRE ,ts 文件 里 声明 一 个 对 @types 包 的 依赖 ， 使 用 --types 命令 行 选项 或 
在 tsconfig.json 里 指定 。 查看 在 tsconfig.json 里 使 
用 @types > typeRoots 和 types 了 解 详情 。 


/// «reference no-default-lib-"true"/» 


这 个 指令 把 一 个 文件 标记 成 默认 库 。 你 会 在 lib.d.ts 文件 和 它 不 同 的 变 体 的 顶 
端 看 到 这 个 注释 。 
这 个 指令 告诉 编译 器 在 编译 过 程 中 不 要 包含 这 个 默认 库 (比如 ， 1ib.d.ts ) ° 


告 
这 与 在 命令 行 上 使 用 --noLib 相似 。 


EN 


还 要 注意 ， 当 传递 了 --skipDefaultLibCheck 时 ， 编 译 器 只 会 忽略 检查 带 有 /// 
<reference no-default-lib="true"/> 的 文件 。 


/// <amd-module /> 


默认 情况 下 生成 的 AMD 模 块 都 是 匿名 的 。 但 是 ， 当 一 些 工 具 需 要 处 理 生 成 的 模块 
时 会 产生 问题 ， 比 如 r.js 。 


amd-module 指令 允许 给 编译 器 传 入 一 个 可 选 的 模块 名 : 


amdModule.ts 


///«amd-module name-'NamedModule'/» 
export class C { 


j 


这 会 将 NamedModule 传 入 到 AMD define S2#: 


amdModule.js 


define("NamedModule", ["require", "exports"], function (require, 
exports) { 
var C = (function () 4 
functyomc o) E 


} 

[aetema C 
3); 
exports.C - C; 


3); 


/// «amd-dependency /» 


注意 : 这 个 指令 被 废 育 了 。 使 用 import "moduleName"; 3i&4]4X e 


/// «amd-dependency path="x" /> 告诉 编译 器 有 一 个 非 TypeScript 模 块 依赖 需 
要 被 注入 ， 做 为 目标 模块 require 调用 的 一 部 分 。 


amd-dependency 指令 也 可 以 带 一 个 可 选 的 name 属性 ; 它 允 许 我 们 为 amd- 
dependency 传 入 一 个 可 选 名 字 : 


/// «amd-dependency path="legacy/moduleA" name="moduleA"/> 
declare var moduleA:MyType 
moduleA.callStuff() 


生成 的 JavaScript 代 码 : 


三 针线 指令 


define(["require", "exports", "legacy/moduleA"], function (requi 
re, exports, moduleA) { 

moduleA.callStuff() 
3); 
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TypeScript 2.3 以 后 的 版 本 支持 使 用 --checkJs 对 ,js 文件 进行 类 型 检查 并 提示 
错误 的 模式 。 


你 可 以 通过 添加 // Qts-nocheck 注释 来 忽略 类 型 检查 ; 相反 你 可 以 通过 去 掉 -- 
checkJs 设置 并 添加 // Qts-check 注释 来 选 则 检查 某 些 .js 文件 。 你 还 可 以 
使 用 // Qts-ignore 来 忽略 本 行 的 错误 。 


下 面 是 一 些 值得 注意 的 类 型 检查 在 .js 文件 与 .ts 文件 上 的 差异 : 


在 JSDoc 上 使 用 类 型 


.js 文件 里 ， 类 型 可 以 和 在 .ts eI 同样 地 ， 当 类 型 不 能 
被 推断 时 ， 它 们 可 以 通过 JSDoc 来 指定 ， 就 好 比 在 .ts 文件 里 那样 。 


JSDoc 注 解 修饰 的 声明 会 被 设置 为 这 个 声明 的 类 型 。 比 如 : 


/** @type {number} */ 


var X; 
X = OF // OK 
x = false; // Error: boolean is not assignable to number 


你 可 以 在 这 里 找到 所 有 JSDoc 支 持 的 模式 ，JSDoc 文 档 。 


类 内 部 赋值 语句 推断 属性 声明 
ES2015/ES6 不 存在 类 属性 的 声明 。 属 性 是 动态 的 赋予 的 ， 就 如 同 对 象 字面 量 一 
样 。 


在 ,js 文件 里 ， 属 性 声明 是 由 类 内 部 的 属性 赋值 语句 推断 出 来 的 。 属 性 的 类 型 是 
赋值 语句 右 侧 所 有 值 的 联合 。 构 造 函 数 里 定义 的 属性 是 永远 存在 的 ， 在 方法 存 取 器 
里 定义 的 被 认为 是 可 选 的 。 


使 用 JSDoc 修 饰 属 性 赋值 来 指定 属性 类 型 。 例 如 


class C 4 
constructor() { 
/** Qtype (number | undefined) */ 
this.prop - undefined; 


let c = new C(); 


c.prop = 0; // OK 
c.prop = "string"; // Error: string is not assignable to number 
| undefined 


如 果 属 性 永远 都 不 在 类 的 内 部 被 设置 ， 那 么 它们 被 当成 是 未 知 的 。 如 果 类 具有 只 读 
的 属性 ， 考 虑 在 构造 函数 里 给 它 初始 化 成 undefined ， 例 如 this.prop = 


undefined; ° 


CommonJS 模 块 输入 支持 


,js 文件 支持 将 CommonJS 模 块 做 为 输入 模块 格式 。 
对 exports 和 module.exports 的 赋值 被 识别 为 导出 声明 。 相似 
地 ， require 函数 调用 被 识别 为 模块 导入 。 例 如 : 


// import module "fs" 
const fs = require("fs"); 


// export function readFile 
module.exports.readFile = function(f) { 
return fs.readFileSync(f); 


对 象 字 面 量 是 开放 的 


默认 地 ， 变 量 声明 中 的 对 象 字面 量 本 身 就 提供 了 类 型 声明 。 新 的 成 员 不 能 被 加 到 对 
象 中 去 。 这 个 规则 在 .js 文件 里 被 放宽 了 ; 对 象 字面 量具 有 开放 的 类 型 ， 人 允许 添 
加 并 访问 原先 没有 定义 的 属性 。 例 如 : 


var obj = {a: 1 }; 
obj.b = 2; // Allowed 


对 象 字 面 量具 有 默认 的 索引 签名 [x:string]: any ， 它 们 可 以 被 当成 开放 的 映射 
而 不 是 封闭 的 对 象 。 


与 其 它 JS 检 查 行 为 相似 ， 这 种 行为 可 以 通过 指定 JSDoc 类 型 来 改变 ， 例 如 : 
/** @type ([a: number}} */ 


var obj = {a: 1 }; 
obj.b = 2; // Error, type {a: number} does not have property b 


次 数 参 数 是 默认 可 选 的 


由 于 JS 不 支持 指定 可 选 参数 (不 指定 一 个 默认 值 )， .js 文件 里 所 有 函数 参数 都 
被 当做 可 选 的 。 使 用 比 预期 少 的 参数 调用 函数 是 允许 的 。 
需要 注意 的 一 点 是 ， 使 用 过 多 的 参数 调用 函数 会 得 到 一 个 错误 。 


例如 : 


function bar(a, b){ 


console.log(a + " " + b); 
} 
bar(1); // OK, second argument considered optional 
bar(1, 2); 


bar(1, 2, 3); // Error, too many arguments 


使 用 JSDoc 注 解 的 函数 会 被 从 这 条 规则 里 移 除 。 使 用 JSDoc 可 选 参 数 语法 来 表示 可 
选 性 。 比 如 : 


* @param {string} [somebody] - Somebody's name. 


function sayHello(somebody) { 
if (!somebody) { 
somebody = 'John Doe'; 


} 

alert('Hello ' + somebody); 
} 
sayHello(); 


由 arguments 推断 出 的 var-args 参 数 声明 


如 果 一 个 函数 的 函数 体内 有 对 arguments 的 引用 ， 那 么 这 个 函数 会 隐 式 地 被 认为 
具有 一 个 var-arg 参 数 ( 比 如: (...arg: any[]) => any )) 。 使 用 JSDoc 的 var- 


arg 语 法 来 指定 arguments 的 类 型 。 


未 指定 的 类 型 参数 默认 为 any 
未 指定 的 泛 型 参数 类 型 将 默认 为 any 。 有 如 下 几 种 情形 : 


f extends? 4] t 


例如 ， React.Component 被 定义 成 具有 两 个 泛 型 参数 ， Props 和 State » 在 
一 个 .js 文件 里 ， 没 有 一 个 合法 的 方式 在 extends 语 名 里 指定 它们 。 默 认 地 参数 类 


型 为 any 


JavaScript # € $5 2E 78 q6 & 


import { Component ) from "react"; 


class MyComponent extends Component ( 
render() ( 
this.props.b; // Allowed, since this.props is of type any 


SSeS ëO 
使 用 JSDoc 的 Qaugments 来 明确 地 指定 类 型 。 例 如 : 


import { Component } from "react"; 


f es 
* @augments {Component<{a: number}, State») 
“7 
class MyComponent extends Component { 
render() { 
this.props.b; // Error: b does not exist on {a:number} 


在 JSDoc 引 用 中 


JSDoc 里 未 指定 的 泛 型 参数 默认 为 any 


335 


/** Qtype(Array) */ 
var x = []; 


x.push(1); // OK 
x.push("string"); // OK, x is of type Array<any> 


/** @type{Array.<number>} */ 
var y - []; 


y.push(1); // OK 
y.push("string"); // Error, string is not assignable to number 
在 函数 调用 中 


泛 型 函数 的 调用 使 用 arguments 来 推断 泛 型 参数 。 有 时 候 ， 这 个 流程 不 能 够 推断 
出 类 型 ， 大 多 是 因为 缺少 推断 的 源 ; 在 这 种 情况 下 ， 泛 型 参数 类 型 默认 为 any 。 
例如 : 


var p = new Promise((resolve, reject) => ( reject() }); 


p; // Promise<any>; 


这 篇 指南 的 目的 是 教 你 如 何 书 写 高 质量 的 TypeScript 声 明文 件 。 


在 这 篇 指南 里 ， 我 们 假设 你 对 TypeScript 已 经 有 了 基本 的 了 解 。 如 果 没 有 ， 请 先 阅 
读 TypeScript 手 册 来 了 解 一 些 基 本 知识 ， 尤 其 是 类 型 和 命名 空间 部 分 


这 篇 指南 被 分 成 了 以 下 章节 。 


结构 


结构 一 节 将 帮助 你 了 解 常见 库 的 格式 以 及 如 何 为 每 种 格式 书写 正确 的 声明 文件 。 如 
果 你 在 编辑 一 个 已 经 存在 的 文件 ， 那 么 你 可 能 不 需要 阅读 此 章节 。 如 果 你 在 书写 新 
的 声明 文件 ， 那 么 你 必须 阅读 此 章节 以 理解 库 的 不 同 格式 是 如 何 影响 声明 文件 的 书 
写 的 。 


ABB 


很 多 时 候 ， 我 们 只 能 通过 一 些 示 例 来 了 解 第 三 方 库 是 如 何 工 作 的 ， 同 时 我 们 需要 为 
这 样 的 库 书 号 声明 文件 。 举例 一 节 展 示 了 很 多 党 UNATE AAAA 
声明 文件 。 这 篇 指南 是 针对 TypeScript 初 学 者 的 ， 它 们 可 能 还 不 了 解 TypeScript 里 
的 所 有 语言 结构 。 


规范 


声明 文件 里 有 很 多 常见 的 错误 是 很 容易 避免 的 。 规范 一 节 指 出 了 常见 的 错误 d 
述 了 如 何 发 现 它们 ， 与 怎样 去 修复 。 每 个 人 都 要 阅读 这 个 章节 以 了 解 如 何 避 免 党 
VR iX 9 


深入 
EE buc M od e MN RUM 节 解 释 了 很 多 高 级 书写 
声明 文件 的 高 级 概念 ， 以 及 展示 了 如 何 利用 这 些 概念 来 创建 整洁 和 直观 的 声明 文 


件 。 


模版 


在 模版 一 节 里 ， 你 能 找到 一 些 声明 文件 ， 它 们 可 以 帮助 你 快速 开始 当 你 在 书写 一 
ee 这 篇 文档 来 找到 应 该 使 用 哪个 模版 文件 。 
发 布 到 npm 


发 布 一 节 讲 解 了 如 何 发 布 声明 文件 为 npm 包 ， 及 如 何 管理 包 的 依赖 。 


查找 与 安装 声明 文件 


一 个 


对 于 JavaScript 库 的 使 用 者 来 讲 ， 使 用 一 节 提 供 了 一 些 简单 步骤 来 定位 与 安装 相应 
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概述 


一 般 来 讲 ， 你 组 织 声明 文件 的 方式 取决 于 库 是 如 何 被 使 用 的 。 在 JavaScript 中 一 个 
库 有 很 多 使 用 方式 ， 这 就 需要 你 书写 声明 文件 去 匹配 它们 。 这 篇 指南 涵盖 了 如 何 识 
别 常见 库 的 模式 ， 和 怎样 书写 符合 相应 模式 的 声明 文件 。 

针对 每 种 主要 的 库 的 组 织 模式 ， 在 模版 一 节 都 有 对 应 的 文件 。 你 可 以 利用 它们 帮助 
你 快速 上 手 。 


识别 库 的 类 型 
首先 ， 我 们 先 看 一 下 TypeScript 声 明文 件 能 够 表示 的 库 的 类 型 。 这 里 会 简单 展示 每 
种 类 型 的 库 的 使 用 方式 ， 如 何 去 书写 ， 还 有 一 些 真 实 案例 。 


识别 库 的 类 型 是 书写 声明 文件 的 第 一 步 。 我们 将 会 给 出 一 些 提 示 ， 关 于 怎样 通过 库 
的 使 用 方法 及 其 源码 来 识别 库 的 类 型 。 根据 库 的 文档 及 组 织 结构 不 同 ， 这 两 种 方式 
可 能 一 个 会 比 另外 的 那个 简单 一 些 。 我 们 推荐 你 使 用 任意 你 喜欢 的 方式 。 


全 局 库 
全 局 库 是 指 能 在 全 局 命名 空间 下 访问 的 (例如 : 不 需要 使 用 任何 形式 
的 import ) 。 许 多 库 都 是 简单 的 暴露 出 一 个 或 多 个 全 局 变量 。 比如， 如 果 你 使 


用 过 jQuery ，$ 变量 可 以 被 够 简单 的 引用 : 


$(() => { console.log('hello!'); } ); 


<script src="http://a.great.cdn.for/someLib.js"></script> 


目前 ， 大 多 数 流行 的 全 局 访问 型 库 实 际 上 都 以 UMD 库 的 形式 进行 书写 〈 见 后 文 ) 。 
UMD 库 的 文档 很 难 与 全 局 库 文 档 两 者 之 间 难 以 区 分 。 在 书写 全 局 声明 文件 前 ， 一 
定 要 确认 一 下 库 是 否 趴 的 不 是 UMD 。 


从 代码 上 识别 全 局 库 
全 局 库 的 代码 通常 都 十 分 简单 。 一 个 全 局 的 “Hello, world" 库 可 能 是 这 样 的 : 


function createGreeting(s) { 
return "Hello, “ + S; 


window.createGreeting - function(s) ( 
return "Hello, " + s; 


当 你 查看 全 局 库 的 源 代码 时 ， 你 通常 会 看 到 : 


e 顶级 的 var 语句 或 function 声明 

e 一 个 或 多 个 赋值 语句 到 window. someName 

e 假设 DOM 原 始 值 像 document 或 window 是 存在 的 
你 不 会 看 到 : 


e 检查 是 否 使 用 或 如 何 使 用 模块 加 载 器 ， 比 如 require 或 define 
e CommonJS/Node.js 风 格 的 导入 如 var fs = require("fs"); 
e define(...) 调用 

e 文档 里 说 明了 如 何 去 require 或 导入 这 个 库 


全 局 库 的 例子 


由 于 把 一 个 全 局 库 转 变 成 UMD 库 是 非常 容易 的 ， 所 以 很 少 流行 的 库 还 再 使 用 全 局 的 
风格 。 然而 ， 小 型 的 且 需 要 DOM (或 没有 依赖 ) 的 库 可 能 还 是 全 局 类 型 的 。 


全 局 库 模 版 


模版 文件 global.d.ts 定义 了 myLib 库 作 为 例子 。 一 定 要 阅读 "防止 命名 证 
突 "补充 说 明 。 


模块 化 库 


一 些 库 只 能 工作 在 模块 加 载 器 的 环境 下 。 比如 ， 像 express 只 能 在 Node.js 里 工 
作 所 以 必须 使 用 CommonJS 的 require 有 函数 加 载 。 


ECMAScript 2015 (也 就 是 ES2015，ECMAScript 6 或 ES6) ，CommonJS 和 
RequireJS 具 有 相似 的 导入 一 个 模块 的 表示 方法 。 例 如 ， 对 于 JavaScript 
CommonJS (Node.js) ， 有 下 面 的 代码 


Vale sho =" TequareQ ies 


对 于 TypeScript 或 ES6， import 关键 字 也 具有 相同 的 作用 : 


import fs = require("fs"); 


你 通常 会 在 模块 化 库 的 文档 里 看 到 如 下 说 明 : 


var someLib = require('someLib'); 


x 
define(..., ['someLib'], function(someLib) { 


3); 


与 全 局 模块 一 样 ， 你 也 可 能 会 在 UMD 模块 的 文档 里 看 到 这 些 例 子 ， 因 此 要 仔细 查看 
源码 和 文档 。 


从 代码 上 识别 模块 化 库 


模块 库 至 少 会 包含 下 列 具有 代表 性 的 条 目 之 一 : 


e 无 条 件 的 调用 require 或 define 
e 4% import * as a from 'b'; or export c; 这 样 的 声明 


e 赋值 给 exports 或 module.exports 


它们 极 少 包含 : 


e 对 window 或 global 的 赋值 


模块 化 库 的 例子 


许多 流行 的 Node.js 库 都 是 这 种 模块 化 的 ， 例 如 express ， gulp 和 request 。 


UMD 


UMD 模 块 是 指 那 些 既 可 以 作为 模块 使 用 (通过 导入 ) 又 可 以 作为 全 局 (在 没有 模块 
加 载 器 的 环境 里 ) 使 用 的 模块 。 许 多 流行 的 库 ， 比 如 Momentjs， 就 是 这 样 的 形 
式 。 比如， 在 Node.js 或 RequireJS 里 ， 你 可 以 这 样 写 : 


import moment = require("moment"); 
console. log(moment.format()); 


然而 在 纯净 的 浏览 器 环境 里 你 也 可 以 这 样 写 : 


console.log(moment.format()); 


识别 UMD 库 


UMD 模块 会 检查 是 否 存在 模块 加 载 器 环境 。 这 是 非常 形容 观察 到 的 模块 ， 它 们 会 
像 下 面 这 样 : 


(function (root, factory) t 
if (typeof define === "function" && define.amd) { 
define(["libName"], factory); 
} else if (typeof module === "object" && module.exports) { 
module.exports = factory(require("libName")); 
} else { 
root.returnExports = factory(root.libName); 


J 
othasscpunct lom Cb) A 


如 果 你 在 库 的 源码 里 看 到 了 typeof define > typeof window * 3 typeof 
module 这 样 的 测试 ， 尤 其 是 在 文件 的 顶端 ， 那 么 它 几乎 就 是 一 个 UMD 库 。 


UMD 库 的 文档 里 经 常会 包含 通过 require “在 Node.js 里 使 用 ”例子 ， 和 “在 浏览 器 
里 使 用 ”的 例子 ， 展 示 如 何 使 用 <script> 标签 去 加 载 脚 本 。 

UMD 库 的 例子 

大 多 数 流行 的 库 现 在 都 能 够 被 当成 UMD 包 。 比如 jQuery,Moment.js,lodash 和 许多 


其 它 的 。 


模版 


针对 模块 有 三 种 可 用 的 模块 ， module.d.ts , module-class.d.ts and 


module-function.d.ts . 


使 用 module-function.d.ts ， 如 果 模 块 能 够 作为 函数 调用 。 


Var x = requaxre( Too"); 
// Note: calling 'x' as a function 
var y = x(42); 
一 定 要 阅读 补充 说 明 :“ES6 模 块 调用 签名 的 影响 ” 
使 用 module-class.d.ts 如 果 模 块 能 够 使 用 new 来 构造 : 
var x = require( bars 


// Note: using 'new' operator on the imported variable 
var y - new x("hello"); 


相同 的 补充 说 明 作用 于 这 些 模块 。 


如 果 模 块 不 能 被 调用 或 构造 ， 使 用 module.d.ts 文件 。 


模块 插件 或 UMD 插 件 


一 个 模块 插件 可 以 改变 一 个 模块 的 结构 (UMD 或 模块 ) 。 例如 ， 在 Moment,js 
里 ， moment-range 添加 了 新 的 range 方法 到 monent 对 象 。 


对 于 声明 文件 的 目标 ， 我 们 会 写 相 同 的 代码 不 论 被 改变 的 模块 是 一 个 纯粹 的 模块 还 
是 UMD 模 块 。 


模版 


使 用 module-plugin.d.ts 模版 。 


全 局 插件 


一 个 全 局 插件 是 全 局 代码 ， 它 们 会 改变 全 局 对 象 的 结构 。 对 于 全 局 修改 的 模块 ， 在 
运行 时 存在 冲突 的 可 能 。 


比如 ， 一 些 库 往 Array.prototype 或 String.prototype 里 添加 新 的 方法 。 


识别 全 局 插件 
全 局 通常 很 容易 地 从 它们 的 文档 识别 出 来 。 


D 
你 会 看 到 像 下 面 这 样 的 例子 : 
var x = "hello, world"; 
// Creates new methods on built-in types 
console.log(x.startswithHello()); 
var y = [1, 2, 3]; 


// Creates new methods on built-in types 
console.log(y.reverseAndSort()); 


模版 


使 用 global-plugin.d.ts 模版 。 


全 局 修改 的 模块 


当 一 个 全 局 修改 的 模块 被 导入 的 时 候 ， 它 们 会 改变 全 局 作用 域 里 的 值 。 比如， 存在 
一 些 库 它 们 添加 新 的 成 员 到 String.prototype 当 导 入 它们 的 时 候 。 这 种 模式 很 
危险 ， 因 为 可 能 造成 运行 时 的 冲突 ， 但 是 我 们 仍然 可 以 为 它们 书写 声明 文件 。 


识别 全 局 修改 的 模块 


全 局 修改 的 模块 通常 可 以 很 容易 地 从 它们 的 文档 识别 出 来 。 通 常 来 讲 ， 它 们 与 全 局 
插件 相似 ， 但 是 需要 require 调用 来 激活 它们 的 效果 。 


你 可 能 会 看 到 像 下 面 这 样 的 文档 : 
// ‘require' call that doesn't use its return value 
var unused = require("magic-string-time"); 
LEO t 
require("magic-string-time"); 
var x = "hello, world"; 
// Creates new methods on built-in types 
console.log(x.startswithHello()); 
var y = [1, 2, 3]; 


// Creates new methods on built-in types 
console.log(y.reverseAndSort()); 


模版 


使 用 global-modifying-module.d.ts 模版 。 
使 用 依赖 
可 能 会 有 以 下 几 种 依赖 。 


依赖 全 局 库 


如 果 你 的 库 依赖 于 某 个 全 局 库 ， 使 用 /// «reference types="..." /> 指令 : 


/// «reference types-"someLib" /> 


function getThing(): someLib.thing; 


= AL 

依赖 模块 

如 果 你 的 库 依赖 于 模块 ， 使 用 import 14 : 
import * as moment from "moment"; 


function getThing(): moment; 


依赖 UMD 库 


从 全 局 库 
如 果 你 的 全 局 库 依赖 于 某 个 UMD 模块 ， 使 用 /// «reference types 指令 : 


/// <reference types="moment" /> 


function getThing(): moment; 


从 一 个 模块 或 UMD 库 


如 果 你 的 模块 或 UMD 库 依 赖 于 一 个 UMD 库 ， 使 用 import 语句: 


import * as someLib from 'someLib'; 


不 要 使 用 /// «reference 指令 去 声明 UMD 库 的 依赖 ! 


补充 说 明 


防止 命名 冲突 


注意 ， 在 书写 全 局 声明 文件 时 ， 允 许 在 全 局 作用 域 里 定义 很 多 类 型 。 我 们 十 分 不 建 
义 这 样 做 ， 当 一 个 工程 里 有 许多 声明 文件 时 ， 它 会 导致 无 法 处 理 的 命名 冲突 。 
一 个 简单 的 规则 是 使 用 库 定义 的 全 局 变量 名 来 声明 命名 空间 类 型 。 比 如 ， 库 定义 了 


一 个 全 局 的 值 cats ， 你 可 以 这 样 写 


declare namespace cats { 
interface KittySettings { } 


不 要 


// at top-level 


interface CatsKittySettings { } 


这 样 也 保证 了 库 在 转换 成 UMD 的 时 候 没 有 任何 的 破坏 式 改 变 ， 对 于 声明 文件 用 户 来 


说 。 
ES6 模 块 插件 的 影响 

一 些 播 件 添加 或 修改 已 存在 的 顶层 模块 的 导出 部 分 。 当然 这 在 CommonJS 和 其 它 
加 载 器 里 是 允许 的 ，ES 模 块 被 当 作 是 不 可 改变 的 因此 这 种 模式 就 不 可 行 了 。 因为 
TypeScript 是 能 不 预知 加 载 器 类 型 的 ， 所 以 没 没 在 编译 时 保证 ， 但 是 开发 者 如 果 要 
转 到 ES6 模 块 加 载 器 上 应 该 注意 这 一 点 。 

ES6 模 块 调用 签名 的 影响 


很 多 流行 库 ， 比 如 Express， 暴 露出 自己 作为 可 以 调用 的 函数 。 比如 ， 典 型 的 
Express 使 用 方法 如 下 : 


import exp = require("express"); 
var app = exp(); 


在 ES6 模 块 加 载 器 里 ， 顶 层 的 对 象 (这 里 以 exp $A) 只 能 具有 属性 ; 顶层 的 模 
块 对 象 永远 不 能 被 调用 。 十 分 常见 的 解决 方法 是 定义 一 个 default 导出 到 一 个 可 
调用 的 /可 构造 的 对 象 ; 一 会 模块 加 载 器 助手 工具 能 够 自己 探测 到 这 种 情况 并 且 使 
用 default 导出 来 替换 顶层 对 象 。 


Number ° String ， Boolean 和 Object 


不 要 使 用 如 下 类 型 Number * String * Boolean X Object 。 这 些 类 型 指 的 


是 非 原 始 的 装 盒 对 象 ， 它 们 几乎 没 在 JavaScript 代 码 里 正确 地 使 用 过 。 


/* 错误 */ 
function reverse(s: String): String; 


应 该 使 用 类 型 number > string >and boolean 。 


EXE KE 
function reverse(s: string): string; 


使 用 非 原始 的 object 类 型 来 代替 object (TypeScript 2.2217$ ) 


泛 型 


不 要 定义 一 个 从 来 没 使 用 过 其 类 型 参数 的 泛 型 类 型 。 了解 详情 TypeScript FAQ 
page ° 


回调 函数 返回 值 类 型 
不 要 为 返回 值 被 忽略 的 回调 函数 设置 一 个 any 类 型 的 返回 值 类 型 : 
/* Wk */ 


function fn(x: () => any) { 


x(); 


应 该 给 返回 值 被 忽略 的 回调 函数 设置 void 类 型 的 返回 值 类 型 : 


/* OK */ 
function fn(x: () => void) { 


x(); 


为 什么 : 使 用 void 相对 安全 ， 因 为 它 防 止 了 你 不 小 心 使 用 x 的 返回 值 


function fn(x: () => void) { 
var k = x(); // oops! meant to do something else 
k.doSomething(); // error, but would be OK if the return typ 
e had been 'any' 


} 


回调 函数 里 的 可 选 参数 


不 要 在 回调 函数 里 使 用 可 选 参 数 除 非 你 丨 的 要 这 入 做: 


interface Fetcher { 
getObject(done: (data: any, elapsedTime?: number) => void): 
void; 


} 


这 里 有 一 种 特殊 的 意义 done 回调 函数 可 能 以 1 个 参数 或 2 个 参数 调用 。 代码 大 
概 的 意思 是 说 这 个 回调 函数 不 在 乎 是 否 有 elapsedTime 参数 ， 但 是 不 需要 把 这 个 
参数 当成 可 选 参 数 来 达到 此 目的 -- 因为 总 是 允许 提供 一 个 接收 较 少 参数 的 回调 函 

数 。 


应 该 写 出 回调 函数 的 非 可 选 参数 : 


/ * OK * / 


interface Fetcher ( 
getObject(done: (data: any, elapsedTime: number) -» void): v 
oid; 


j 


重 载 与 回调 函数 
不 要 因为 回调 函数 参数 个 数 不 同 而 写 不 同 的 重 载 : 


/* 错误 */ 

declare function beforeAll(action: () => void, timeout?: number) 
: void; 

declare function beforeAll(action: (done: DoneFn) => void, timeo 
ut?: number): void; 


小 


应 该 只 使 用 最 大 参数 个 数 写 一 个 重 载 : 


/* OK */ 
declare function beforeAll(action: (done: DoneFn) => void, timeo 
ut?: number): void; 
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为 什么 : 回调 函数 总 是 可 以 忽略 某 个 参数 的 ， 因 此 没 必要 为 参数 少 的 情况 写 重 载 。 
参数 少 的 回调 函数 首先 允许 错误 类 型 的 函数 被 传 入 ， 因 为 它们 匹配 第 一 个 重 载 。 


i 


顺序 


不 要 把 一 般 的 重 载 放 在 精确 的 重 载 前 面 : 


[OG 7 

declare function fn(x: any): any; 

declare function fn(x: HTMLElement): number; 
declare function fn(x: HTMLDivElement): string; 


var myElem: HTMLDivElement; 
var x = fn(myElem); // x: any, wat? 


应 该 排序 重 载 令 精 确 的 排 在 一 般 的 之 前 : 


LO Kony: 

declare function fn(x: HTMLDivElement): string; 
declare function fn(x: HTMLElement): number; 
declare function fn(x: any): any; 


var myElem: HTMLDivElement; 
var x - fn(myElem); // x: string, :) 


为 什么 : TypeScript 会 选择 第 一 个 匹配 到 的 重 载 当 解 析 函 数 调用 的 时 候 。 当前 面 的 
重 载 比 后 面 的 “普通 "， 那 么 后 面 的 被 隐藏 了 不 会 被 调用 。 


使 用 可 选 参 数 
不 要 为 仅 在 末 尼 参数 不 同时 写 不 同 的 重 载 : 


"UE re Qui 
interface Example { 
diff(one: string): number; 
diff(one: string, two: string): number; 
diff(one: string, two: string, three: boolean): number; 


ZOK 
interface Example { 
diff(one: string, two?: string, three?: boolean): number; 


WwW 


注意 这 在 所 有 重 载 都 有 相同 类 型 的 返回 值 时 会 不 好 用 。 
为 什么 : 有 以 下 两 个 重要 原因 。 


TypeScript 解 析 签 名 兼容 性 时 会 查看 是 否 某 个 目标 签名 能 够 使 用 源 的 参数 调用 ， 且 
允许 外 来 参数 。 下 面 的 代码 暴露 出 一 个 bug， 当 签名 被 正确 的 使 用 可 选 参 数 书 写 
时 : 


function fn(x: (a: string, b: number, c: number) => void) { } 
var x: Example; 

// When written with overloads, OK -- used first overload 

// When written with optionals, correctly an error 
fn(x.diff); 


$ — JR Be 318 T TypeScript P #7 &null iE o 因为 没有 指定 的 参数 在 
JavaScript 里 表示 为 undefined ， 通 常 显 示 地 为 可 选 参 数 传 入 一 个 undefined ° 
这 段 代码 在 严格 null 模 式 下 可 以 工作 : 


var X: Example; 

// When written with overloads, incorrectly an error because of 
passing 'undefined' to 'string' 

// When written with optionals, correctly OK 
x.diff("something", true ? undefined : "hour"); 


使 用 联合 类 型 


不 要 为 仅 在 茶 个 位 置 上 的 参数 类 型 不 同 的 情况 下 定义 重 载 : 


/* WRONG */ 

interface Moment { 
utcOffset(): number; 
utcOffset(b: number): Moment; 
utcOffset(b: string): Moment; 


应 该 尽 可 能 地 使 用 类 型 类 型 : 


Pe Oe 
interface Moment { 
utcOffset(): number; 
utcOffset(b: number|string): Moment; 


注意 我 们 没有 让 b 成 为 可 选 的 ， 因 为 签名 的 返回 值 类 型 不 同 。 


为 什么 : This is important for people who are "passing through" a value to your 
function: 


FUNC CLONE thc String): vod; 
function fn(x: number): void; 
function fn(x: number|string) { 
// When written with separate overloads, incorrectly an error 


// When written with union types, correctly OK 
return moment().utcOffset(x); 


[ER 


简介 


这 篇 指南 的 目的 是 教 你 如 何 书写 高 质量 的 TypeScript 声 明文 件 。 我 们 在 这 里 会 展示 
一 些 API 的 文档 ， 还 有 它们 的 使 用 示例 ， 并 且 阅 述 了 如 何 为 它们 书写 声明 文件 。 


例子 是 按 复杂 度 递增 的 顺序 组 织 的 。 


e 全 局 变量 

e 全 局 函数 

e 带 属性 的 对 象 

e SHER 

e 可 重用 类 型 (接口 ) 

e 可 重用 类 型 (类 型 别名 ) 


e 组 织 类 型 


2N Te 


全 局 变量 foo 包含 了 存在 组 件 总 数 。 


console.log("Half the number of widgets is " + (foo / 2)); 


声明 


日 


使 用 declare var 声明 变量 。 如 果 变 量 是 只 读 的 ， 那 么 可 以 使 用 declare 
const 。 你 还 可 以 使 用 declare let 如 果 变 量 拥 有 块 级 作用 域 。 


A/ 
declare var foo: number; 


7 
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数 调用 greet 函数 向 用 户 显 示 一 条 欢迎 1 


文档 
用 一 个 字符 囊 参 


代码 
greet("hello, world"); 
声明 
使 用 declare function 声明 函数 。 


declare function greet(greeting: string): void; 


数 ， 还 有 一 个 属 


Ar JB, VEY A 
性 numberOfGreetings 指示 目前 为 止 欢迎 数量 。 


文档 
全 局 变量 myLib 包含 一 个 makeGreeting i£ 


myLib.makeGreeting("hello, world"); 


代码 


let result 


console.log("The computed greeting is:" + result); 
myLib.numberOfGreetings; 


let count 
声明 
使 用 declare namespace 描述 用 点 表示 法 访问 的 类 型 或 值 。 


declare namespace myLib { 
function makeGreeting(s: string): string; 
let numberOfGreetings: number; 


文档 


getWidget 函数 接收 一 个 数字 ， 返 回 一 个 组 件 ， 或 接收 一 个 字符 串 并 返回 一 
个 组 件数 组 。 


代码 
let x: Widget = getWidget(43); 


let arr: Widget[] = getWidget("all of them"); 


声明 


declare function getWidget(n: number): Widget; 
declare function getWidget(s: string): Widget[]; 


可 重用 类 型 (接口 ) 
文档 


妆 指 定 一 个 欢迎 词 时 ， 你 必须 传 入 一 个 GreetingSettings IR ° 这 个 对 象 
具有 以 下 几 个 属性 : 


1- greeting : 必需 的 字符 串 
2- duration: Tit k (SHR) 
3- color: T EB > Pow HffOOff 


代码 


2L7 
OUI 


greet (1 
greeting: "hello world", 
duration: 4000 


3); 


声明 
使 用 interface 定义 一 个 带 有 属性 的 类 型 。 
interface GreetingSettings { 
greeting: string; 


duration?: number; 
color?: string; 


declare function greet(setting: GreetingSettings): void; 


文档 
在 任何 需要 欢迎 词 的 地 方 ， 你 可 以 提供 一 个 string ， 一 个 返回 string 的 
函数 或 一 个 Greeter 实例 。 

代码 


function getGreeting() { 
return "howdy"; 


} 


class MyGreeter extends Greeter { } 


greet("hello"); 
greet(getGreeting); 
greet(new MyGreeter()); 


声明 


你 可 以 使 用 类 型 别名 来 定义 类 型 的 短 名 : 


type GreetingLike = string | (() => string) | MyGreeter; 


declare function greet(g: GreetingLike): void; 


组 织 类 型 
文档 
greeter 对 象 能 够 记录 到 文件 或 显示 一 个 警告 。 你 可 以 为 ,1og(， 


LogOptions 和 为 .alert(...) 提供 选项 。 


代码 


const g = new Greeter("Hello"); 
g.log({ verbose: true }); 
g.alert({ modal: false, title: "Current Greeting" }); 


声明 


使 用 命名 空间 组 织 类 型 。 


declare namespace GreetingLib { 

interface LogOptions { 
verbose?: boolean; 

} 

interface AlertOptions { 
modal: boolean; 
title?: string; 
color?: string; 


Ran TV E-BAY exe RM EI: 


20) 提供 


declare namespace GreetingLib.Options { 
// Refer to via GreetingLib.Options.Log 
interface Log { 
verbose?: boolean; 


} 


interface Alert { 
modal: boolean; 
title?: string; 
color?: string; 


文档 


你 可 以 通过 实例 化 Greeter 对 象 来 创建 欢迎 词 ， 或 者 继承 Greeter 对 象 来 
自 定义 欢迎 词 。 


代码 


const myGreeter = new Greeter("hello, world"); 
myGreeter.greeting = "howdy"; 
myGreeter.showGreeting(); 


class SpecialGreeter extends Greeter { 
constructor() { 
super("Very special greetings"); 


声明 


使 用 declare class 描述 一 个 类 或 像 类 一 样 的 对 象 。 类 可 以 有 属性 和 方法 ， 就 和 
构造 函数 一 样 。 


declare class Greeter { 
constructor(greeting: string); 


greeting: string; 
showGreeting(): void; 


声明 文件 原理 : 深入 探究 


组 织 模块 以 提供 你 想 要 的 API 形 式 保持 一 致 是 比较 难 的 。 比如 ， 你 可 能 想 要 这 样 一 
个 模块 ， 可 以 用 或 不 用 new 来 创建 不 同 的 类 型 ， 在 不 同 层级 上 暴露 出 不 同 的 命名 
类 型 ， 且 模块 对 象 上 还 带 有 一 些 属性 。 


闻 读 这 篇 指定 后 ， 你 就 会 了 解 如 果 书 写 复杂 的 暴露 出 友好 API 的 声明 文件 。 这 篇 指 
定 针对 于 模块 (UMD) 库 ， 因 为 它们 的 选择 具有 更 高 的 可 变性 。 


核心 概念 


如 果 你 理解 了 一 些 关于 TypeScript 是 如 何 工作 的 核心 概念 ， 那 么 你 就 能 够 为 任何 结 
构 书 写 声明 文件 。 

类 型 

如 果 你 正在 阅读 这 篇 指南 ， 你 可 能 已 经 大 概 了 解 TypeScript 里 的 类 型 指 是 什么 。 明 
确 一 下 ， 类 型 通过 以 下 方式 引入 : 


e 类 型 别名 声明 ( type sn = number | string; ) 
e 接口 声明 ( interface I ( x: number[]; } ) 
e 类 声明 ( classC ( } ) 

e APA ( enum E { A, B, € ) ) 

e 指向 某 个 类 型 的 import 声明 


以 上 每 种 声明 形式 都 会 创建 一 个 新 的 类 型 名 称 。 


值 


与 类 型 相 比 ， 你 可 能 已 经 理解 了 什么 是 值 。 值 是 运行 时 名 字 ， 可 以 在 表达 式 里 引 
Hl» mde let x = 5; 创建 一 个 名 为 x 的 1 


o 


E 


同样 ， 以 下 方式 能 够 创建 值 : 


e let ^ const ， 和 var 声明 
e 包含 值 的 namespace X module 声明 


e enum 声明 
e class 声明 
e 指向 值 的 import 声明 


e function 声明 


命名 空间 
类 型 可 以 存在 于 命名 空间 里 。 比如 ， 有 这 样 的 声明 let x: A.B.C ， 我 们 就 认 
Ac 类 型 来 自 A.B 命名 空间 。 


这 个 区 别 虽 细微 但 很 重要 -- 这 里 ， ALB 不 是 必需 的 类 型 或 值 。 


简单 的 组 合 : 一 个 名 字 ， 多 种 意 》 


一 个 给 定 的 名 字 A ， 我 们 可 以 找 出 三 种 不 同 的 意义 : 一 个 类 型 ， 一 个 值 或 一 个 命 
名 空间 。 要 如 何 去 解 析 这 个 名 字 要 看 它 所 在 的 上 下 文 是 怎样 的 。 比如， 在 声 

明 let m: A.A = A; ^ A 首先 被 当做 命名 空间 ， 然 后 做 为 类 型 名 ， 最 后 是 值 。 
这 些 意义 最 终 可 能 会 指向 完全 不 同 的 声明 | 


这 看 上 去 另 人 迷惑 ， 但 是 只 要 我 们 不 过 度 的 重 载 这 还 是 很 方便 的 。 下 面 让 我 们 来 看 
看 一 些 有 用 的 组 合 行为 。 


内 置 组 合 


眼 尖 的 读者 可 能 会 注意 到 ， 比 如， class 同时 出 现在 类 型 和 值 列表 里 。 class C 
{} 声明 创建 了 两 个 东西 : 类 型 C 指向 类 的 实例 结构 ， 值 C 指向 类 构造 函数 。 
枚 举 声明 拥有 相似 的 行为 。 


用 户 组 合 
假设 我 们 写 了 模块 文件 foo.d.ts : 


export var SomeVar: { a: SomeType }; 
export interface SomeType { 
count: number; 


这 样 使 用 它 : 


import * as foo from './foo'; 
let x: foo.SomeType = foo.SomeVar.a; 
console.log(x.count); 


这 可 以 很 好 地 工作 ， 但 是 我 们 知道 和 SomeVar 很 相关 因此 我 们 想 让 
他 们 有 相同 的 名 字 。 我 们 可 以 使 用 组 合 通过 相同 的 名 字 Bar 表示 这 两 种 不 同 的 对 
KR (Abi Fe A) 


export var Bar: { a: Bar }; 
export interface Bar { 
count: number; 


这 提供 了 解构 使 用 的 机 会 : 


import { Bar } from './foo'; 
let x: Bar = Bar.a; 
console.log(x.count); 


再 次 地 ， 这 里 我 们 使 用 Bar 做 为 类 型 和 值 。 注 意 我 们 没有 声明 Bar 值 为 Bar X 
型 -- 它们 是 独立 的 。 


高 级 组 合 
有 一 些 声明 能 够 通过 多 个 声明 组 合 。 比如 ， class C { ) 和 interface C { 
} Kd e Me c 类 型 的 属性 。 


只 要 不 产生 冲突 就 是 合法 的 。 一 个 普通 的 规则 是 值 总 是 会 和 同名 的 其 它 值 产 生 冲 突 
除非 它们 在 不 同 命名 空间 里 ， 类 型 冲突 则 发 生 在 使 用 类 型 别名 声明 的 情况 下 
( type s = string ) ， 命 名 空间 永远 不 会 发 生 冲 突 。 


让 我 们 看 看 如 何 使 用 。 


利用 interface 添加 


我 们 可 以 使 用 一 个 interface 往 别 一 个 interface 声明 里 添加 额外 成 员 : 


interface Foo { 
x: number; 
} 
// ... elsewhere 
interface Foo ( 
y: number; 
} 
let a: Foo = ...; 
console.log(a.x + a.y); // OK 


这 同样 作用 于 类 : 


class Foo { 
x: number; 


} 


// ... elsewhere 
interface Foo ( 
y: number; 


j 


let a: Foo = ...; 
console.log(a.x * a.y); // OK 


注意 我 们 不 能 使 用 接口 往 类 型 别名 里 添加 成 员 ( type s = string; ) 


使 用 namespace 添加 
namespace 声明 可 以 用 来 添加 新 类 型 ， 值 和 命名 空间 ， 只 要 不 出 现 冲 突 。 


比如 ， 我 们 可 能 添加 静态 成 员 到 一 个 类 : 


class C { 
} 


// ... elsewhere ... 
namespace C ( 
export let x: number; 


j 
let y = C.x; // OK 


注意 在 这 个 例子 里 ， 我 们 添加 一 个 值 到 c 的 静态 部 分 ( 它 的 构造 函数 ) 。 这 里 因 
为 我 们 添加 了 一 个 值 ， 且 其 它 值 的 容器 是 另 一 个 值 《类 型 包含 于 命名 空间 ， 命 名 空 
间 包 含 于 另外 的 命名 空间 ) 。 


我 们 还 可 以 给 类 添加 一 个 命名 空间 类 型 : 


Glass © 4 
} 
// ... elsewhere 


namespace C ( 
export interface D { } 


j 
det y: CD 77 Ok 


在 这 个 例子 里 ， 直 到 我 们 写 了 namespace 声明 才 有 了 命名 空间 C 。 做 为 命名 空 
间 的 C 不 会 与 类 创建 的 值 C 或 类 型 C 相互 冲突 。 


最 后 ， 我 们 可 以 进行 不 同 的 合并 通过 namespace 声明 。 Finally we could perform 
many different merges using namespace declarations. This isn't a particularly 
realistic example, but shows all sorts of interesting behavior: 


namespace X { 
export interface Y { } 
export class Z { ) 


// ... elsewhere ... 
namespace X ( 
export var Y: number; 
export namespace Z ( 
export class C { } 


j 
type X = string; 


在 这 个 例子 里 ， 第 一 个 代码 块 创建 了 以 下 名 字 与 含义 : 


e 一 个 值 X (AA namespace 声明 包含 一 个 值 ，Z ) 

e 一 个 命名 空间 X (AA namespace 声明 包含 一 个 值 ，Z ) 
e 在 命名 空间 X 里 的 类 型 y 

e 在 命名 空间 X 里 的 类 型 Z (类 的 实例 结构 ) 

e i x 的 一 个 属性 值 Z (类 的 构造 函数 ) 


第 二 个 代码 块 创建 了 以 下 名 字 与 含义 : 


e 值 Y ( number 类 型 ) ， 它 是 值 x 的 一 个 属性 
e 一 个 命名 空间 z 

e 值 Z > CZE X 的 一 个 属性 

e 在 X.Z 命名 空间 下 的 类 型 C 

e 值 x.z 的 一 个 属性 值 C 

e 类 型 x 


使 用 export = 或 import 


一 个 重要 的 原则 是 export 和 import 声明 会 导出 或 导入 目标 的 所 有 含义 。 


现在 我 们 已 经 按照 指南 里 的 步骤 写 好 一 个 声明 文件 ， 是 时 候 把 它 发 布 到 npm 了。 有 
两 种 主要 方式 用 来 发 布 声明 文件 到 npm : 


1. 与 你 的 npm 包 捆绑 在 一 起 ， 或 
2. 发 布 到 npm 上 的 @types organization ° 


如 果 你 能 控制 要 使 用 你 发 布 的 声明 文件 的 那个 npm 包 的 话 ， 推 荐 第 一 种 方式 。 这 样 
的 话 ， 你 的 声明 文件 与 JavaScript 总 是 在 一 起 传递 。 


包含 声明 文件 到 你 的 npm 包 


如 果 你 的 包 有 一 个 主 ,js 文件 ， 你 还 是 需要 在 package.json 里 指定 主 声明 文 
件 。 设置 types 属性 指向 捆绑 在 一 起 的 声明 文件 。 比 如 : 


{ 
"name": "awesome", 
"author": "Vandelay Industries", 
IVEES LOM RD 有 OU 
mann "7 lib/mMain. is"; 
‘types: TT b/Amaum-d- ts" 

} 


注意 "typings" 5 "types" 具有 相同 的 意义 ， 也 可 以 使 用 它 。 


同样 要 注意 的 是 如 果 主 声明 文件 名 是 index.d.ts 并 且 位 置 在 包 的 根 目 录 里 
(与 index.js 并 列 ) ， 你 就 不 需要 使 用 "types" 属性 指定 了 。 


依赖 


所 有 的 依赖 是 由 npm 管 理 的 。 确保 所 依赖 的 声明 包 都 
在 package.json 的 "dependencies" 里 指明 了 比如 ， 假 设 我 们 写 了 一 个 包 它 依 
$ T Browserify#? TypeScript 。 


"name": "browserify-typescript-extension", 
"author": "Vandelay Industries", 
ZVersdonhes c T. 0 po 

"hain: C/TI3b/mazm.js-. 

‘types: “./lib/main.d.ts, 


"dependencies": { 
"browserify": "latest", 
"Qtypes/browserify": "latest", 
"typescript": "next" 


这 里 ， 我 们 的 包 依 赖 于 browserify 和 typescript 包 。 browserify 没有 把 
它 的 声明 文件 捆绑 在 它 的 npm 包 里 ， 所 以 我 们 需要 依赖 于 @types/browserify 得 
到 它 的 声明 文件 。 typescript 相反 ， 它 把 声明 文件 放 在 了 npm 包 里 ， 因 此 我 们 
不 需要 依赖 额外 的 包 


我 们 的 包 要 从 这 两 个 包 里 暴露 出 声明 文件 ， 因 此 browserify-typescript- 
extension 的 用 户 也 需要 这 些 依赖 。 正 因此 ， 我 们 使 用 "dependencies" 而 不 
是 "devDependencies" ， 否 则 用 户 将 需要 手动 安装 那些 包 。 如 果 我 们 只 是 在 写 
一 个 命令 行 应 用 ， 并 且 我 们 的 包 不 会 被 当做 一 个 库 使 用 的 话 ， 那 么 我 就 可 以 使 


用 devDependencies ° 


危险 信号 


/// <reference path="..." /> 
不 要 在 声明 文件 里 使 用 /// «reference pathz"..." /> » 
/// <reference path="../typescript/lib/typescriptServices.d.ts" 


(= 


应 该 使 用 /// «reference types="..." /> 代替 


/// «reference types="typescript" /> 


务必 阅读 使 用 依赖 一 节 了 解 详 情 。 


打包 所 依赖 的 声明 
如 果 你 的 类 型 声明 依赖 于 另 一 个 包 : 


e. 不 要 把 依赖 的 包 放 进 你 的 包 里 ， 保 持 它们 在 各 自 的 文件 里 。 
e 不 要 将 声明 拷贝 到 你 的 包 里 。 
e 应 该 依赖 于 npm 类 型 声明 包 ， 如 果 依 赖 包 没 包含 它 自己 的 声明 的 话 。 


公布 你 的 声明 文件 


在 发 布 声明 文件 包 之 后 ， 确 保 在 DefinitelyTyped 外 部 包 列 表 里 面 添加 一 条 引用 。 这 
可 以 让 查找 工具 知道 你 的 包 提供 了 自己 的 声明 文件 。 


发 布 到 @types 


types 下 面 的 包 是 从 DefinitelyTyped 里 自动 发 布 的 ， 通 过 types-publisher 工 具 。 如 
果 想 让 你 的 包 发 布 为 @types 包 ， 提 交 一 个 pull request 

到 https://github.com/DefinitelyTyped/DefinitelyTyped。 在 这 里 查看 详细 信 

息 contribution guidelines page ° 


在 TypeScript 2.0， 获 取 、 使 用 和 查找 声明 文件 变 得 十 分 容易 。 这 篇 文章 将 详细 说 
明 怎 么 做 这 三 件 事 。 


在 TypeScript 2.0 以 上 的 版 本 ， 获 取 类 型 声明 文件 只 需要 使 用 npm » 


比如 ， 获 取 lodash 库 的 声明 文件 ， 只 需 使 用 下 面 的 命令 : 


npm install --save @types/lodash 


如 果 一 个 npm 包 像 Publishing 里 所 讲 的 一 样 已 经 包含 了 它 的 声明 文件 ， 那 就 不 必 再 
去 下 载 相 应 的 @types 包 了 。 


使 用 


下 载 完 后 ， 就 可 以 直接 在 TypeScript 里 使 用 lodash 了 。 不 论 是 在 模块 里 还 是 全 局 代 
码 里 使 用 。 


比如 ， 你 已 经 npm install 安装 了 类 型 声明 ， 你 可 以 使 用 导入 : 


import * as _ from "lodash"; 
—.padStart('"Hello TypeScript!" 26," 1); 


或 者 如 果 你 没有 使 用 模块 ， 那 么 你 只 需 使 用 全 局 的 变量 c 


_.padStart("Hello TypeScript!", 20, " ys 


查找 


大 多 数 情 况 下 ， 类 型 声明 包 的 名 字 总 是 与 它们 在 npm 上 的 包 的 名 字 相 同 ， 但 是 
有 @types/ 前 级 ， 但 如 果 你 需要 的 话 ， 你 可 以 在 https://aka.ms/types 这 里 查找 你 
喜欢 的 库 。 


使 用 


注意 : 如 果 你 要 找 的 声明 文件 不 存在 ， 你 可 以 贡献 一 份 ， 这 样 就 方便 了 下 一 位 
要 使 用 它 的 人 。 查看 DefinitelyTyped 贡 献 指 南 页 了 解 详情 。 
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概述 


如 果 一 个 目录 下 存在 一 个 tsconfig.json 文件 ， 那 么 它 意 味 着 这 个 目录 是 
TypeScript 项 目的 根 目 录 。 tsconfig.json 文件 中 指定 了 用 来 编译 这 个 项 目的 根 
文件 和 编译 选项 。 一 个 项 目 可 以 通过 以 下 方式 之 一 来 编译 : 


使 用 tsconfig.json 


e 不 带 任何 输入 文件 的 情况 下 调用 tsc ， 编 译 器 会 从 当前 目录 开始 去 查 
找 tsconfig.json 文件 ， 乏 级 向 上 搜索 父 目 录 。 

e 不 带 任何 输入 文件 的 情况 下 调用 tsc ， 且 使 用 命令 行 参数 -- 
project (或 -p ) 指定 一 个 包含 tsconfig.json 文件 的 目录 。 


当 命 令 行 上 指定 了 输入 文件 时 ， tsconfig.json 文件 会 被 忽略 。 
示例 


tsconfig.json 示例 文件 : 


e 使 用 "files" 属性 


工程 配置 


"compilerOptions": { 
"module": "commonjs", 
"noImplicitAny": true, 
"removeComments": true, 
"preserveConstEnums": true, 
"sourceMap": true 

i 

"files": [ 

"core.ts", 

sys tsi, 

UEVpPeS ts 
"scanner.ts", 
"parser.ts", 
"utilities.ts", 
"binder.ts", 
"checker.ts", 
"emitter.ts", 
"program.ts", 
"commandLineParser.ts", 
MESC yes; 
"diagnosticInformationMap.generated.ts" 


e 使 用 "include" 和 "exclude" 属性 
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"compilerOptions": { 
"module": "system", 
"noImplicitAny": true, 
"removeComments": true, 
"oreserveConstEnums": true, 
oUt Ee c a7 DURE /LOGaAI~eSG ss 
"sourceMap": true 


3 

«includes 
rey oer SM 

] 


"exclude": [ 
"node modules", 
> spacsrs 


细节 


"compilerOptions" 可 以 被 忽略 ， 这 时 编译 器 会 使 用 默认 值 。 在 这 里 查看 完整 的 
编译 器 选项 列表 。 


"files" 指定 一 个 包含 相对 或 绝对 文件 路 径 的 列表 。 
"include" 和 "exclude" 属性 指定 一 个 文件 glob 匹 配 模式 列表 。 支持 的 glob 通 
配 符 有 : 


e * 匹配 0 或 多 个 字符 〈 不 包括 目录 分 隔 符 ) 
e ? 匹配 一 个 任意 字符 (不 包括 目录 分 隔 符 ) 
e **/ 递归 匹配 任意 子 目 录 


如 果 一 个 glob 模 式 里 的 茶 部 分 只 包含 * 或 .* ， 那 么 仅 有 支持 的 文件 扩展 名 类 型 
被 包含 在 内 (比如 默认 .ts ， .tsx ， 和 .d.ts ， 如 果 allowJs 设置 

能 true 还 包含 ,js 和 .jsx ) » 

如 果 "files" 和 "include" 都 没有 被 指定 ， 编 译 器 默认 包含 当前 目录 和 子 目 录 


下 所 有 的 TypeScript 文 件 ( .ts , .d.ts 和 .tsx ) ， 排 除 在 "exclude" 里 指 
定 的 文件 。 JS 文件 ( .js 和 ,jsx ) 也 被 包含 进来 如 果 allowJs 被 设置 


成 true 。 如 果 指 定 了 "files" X "include" ， 编 译 器 会 将 它们 结合 一 并 包含 
进来 。 使 用 "outDir" 指定 的 目录 下 的 文件 永远 会 被 编译 器 排除 ， 除 非 你 明确 地 
使 用 "files" 将 其 包含 进来 (这 时 就 算 用 exclude 指定 也 没 用 ) © 


使 用 "include" 引入 的 文件 可 以 使 用 "exclude" 属性 过 滤 。 然而 ， 通 

过 "files" 属性 明确 指定 的 文件 却 总 是 会 被 包含 在 内 ， 不 管 "exclude" 如 何 设 
置 。 如 果 没 有 特殊 指定 ， "exclude" 默认 情况 下 会 排 

除 node modules ， bower components * jspm_packages 和 <outDir> 4H 


io 


任何 被 "files" X "include" 指定 的 文件 所 引用 的 文件 也 会 被 包含 进来 。 
A.ts 引用 了 B.ts ， 因 此 B.ts 不 能 被 排除 ， 除 非 引用 它 
的 Ats 在 "exclude" 列表 中 。 


需要 注意 编译 器 不 会 去 引入 那些 可 能 做 为 输出 的 文件 ; 比如 ， 假 设 我 们 包含 
了 index.ts ， 那 么 index.d.ts 和 index.js 会 被 排除 在 外 。 通常 来 讲 ， 不 推 
戎 只 有 扩展 名 的 不 同 来 区 分 同 目录 下 的 文件 。 


tsconfig.json 文件 可 以 是 个 空 文件 ， 那 么 所 有 默认 的 文件 (如 上 面 所 述 ) 都 会 
以 默认 配置 选项 编译 。 


在 命令 行 上 指定 的 编译 选项 会 覆盖 在 tsconfig.json 文件 里 的 相应 选项 。 


@types ， typeRoots 和 types 


默认 所 有 可 见 的 " Otypes " 包 会 在 编译 过 程 中 被 包含 进来 。 

node modules/Qtypes 文件 夹 下 以 及 它们 子 文件 夹 下 的 所 有 和 包 都 是 可 见 的 ; 也 
说 ， ./node modules/Qtypes/ * ../node_modules/@types/ 和 ../../node 
_modules/@types/ 等 等 。 


如 果 指 定 了 typeRoots ， 只 有 typeRoots 下 面 的 包 才 会 被 包含 进来 。 比如 : 


"compilerOptions": { 
"typeRoots" : ["./typings"] 


这 个 配置 文件 会 包含 所 有 ./typings 下 面 的 包 ， 而 不 包 
4- ./node modules/Qtypes 里 面 的 包 。 


如 果 指 定 了 types ， 只 有 被 列 出 来 的 包 才 会 被 包含 进来 。 比如 : 


"compilerOptions": { 
"types" : ["node", "lodash", "express"] 


这 个 tsconfig.json 文件 将 仅 会 包含 

./node_modules/@types/node * ./node_modules/@types/lodash 和 ./nod 
e modules/Qtypes/express °/@types/° node modules/Qtypes/* 里 面 的 其 
它 包 不 会 被 引入 进来 。 


指定 "types": [] 来 禁用 自动 引入 @types Be 


注意 ， 自 动 引 入 只 在 你 使 用 了 全 局 的 声明 (相反 于 模块 ) 时 是 重要 的 。 如 果 你 使 
用 import "foo" 语句 ，TypeScript 仍 然 会 查 
找 node modules 和 node modules/Qtypes 文件 夹 来 获取 foo 包 。 


使 用 extends 继承 配置 
tsconfig.json 文件 可 以 利用 extends 属性 从 另 一 个 配置 文件 里 继承 配置 。 


extends 是 tsconfig.json 文件 里 的 顶级 属性 
(与 compileroptions ， files ， include ， 和 exclude 一 样 ) 。 
extends 的 值 是 一 个 字符 事 ， 和 包含 指向 另 一 个 要 继承 文件 的 路 径 。 


在 原文 件 里 的 配置 先 被 加 载 ， 然 后 被 来 至 继承 文件 里 的 配置 重 写 。 如 果 发 现 循环 引 
用 ， 则 会 报错 。 


来 至 所 继承 配置 文件 的 files ， include 和 exclude 埠 盖 源 配置 文件 的 属性 。 
配置 文件 里 的 相对 路 径 在 解析 时 相对 于 它 所 在 的 文件 。 
比如 : 


configs/base. json 


"compilerOptions": { 
"noImplicitAny": true, 
"strictNullChecks": true 


tsconfig.json 


{ 
"extends": "./configs/base", 
amies se 
"ma-zmnets' 
"supplemental.ts" 
] 
} 


tsconfig.nostrictnull.json 


"extends": ".7tsconfig", 
"compilerOptions": { 
"strictNullChecks": false 


compileOnSave 


在 最 顶层 设置 compileOnSave 标记 ， 可 以 让 IDE 在 保存 文件 的 时 候 根 
据 tsconfig.json 重新 生成 文件 。 


"compileOnSave": true, 
"compilerOptions": { 
"noImplicitAny" : true 


要 想 支 持 这 个 特性 需要 Visual Studio 2015 > TypeScript1.8.474 # E. 3c X atom- 
typescript 插 件 。 


模式 


到 这 里 查看 模式 : http://json.schemastore.org/tsconfig. 


NPM 包 的 类 型 


本 页 面 被 移动 到 书写 声明 文件 页 
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编译 选项 


--allowJs 
--allowSyntheticDefaultImports 


- -allowUnreachableCode 
- allowUnusedLabels 
--alwaysStrict 

- -baseUr1 

--charset 

--checkJs 


--declaration 
-d 


--declarationDir 
--diagnostics 
--disableSizeLimit 

- -emitBOM 
--emitDecoratorMetadata [1] 


--experimentalDecorators [1] 


forceConsistentCasingInFileNames 


- -help 
-h 


--importHelpers 


--inlineSourceMap 
--inlineSources 
--init 


--isolatedModules 


RA 


boolean 


boolean 


boolean 
boolean 
boolean 
string 
string 


boolean 
boolean 


string 

boolean 
boolean 
boolean 
boolean 


boolean 


boolean 


string 


boolean 


boolean 


boolean 


Rita 
false 


module === 
"system" 或 -- 
esModuleInterop 


false 
false 


false 


"utf8" 


false 


false 


false 
false 
false 
false 


false 


false 


false 


false 


false 


--jsx string "Preserve" 


--jsxFactory string "React.createElem 
- -lib string[] 

--listEmittedFiles boolean false 

--listFiles boolean false 


--locale string (platform specific) 


- mapRoot 


- -maxNodeModuleJsDepth 


- -module 
-m 


- moduleResolution 


- -newLine 

- -noEmit 
--noEmitHelpers 

- -noEmitOnError 
--noErrorTruncation 

- -noFallthroughCasesInSwitch 
- -noImplicitAny 
--noImplicitReturns 
--noImplicitThis 
--noImplicitUseStrict 

- -noLib 

- -noResolve 
--noStrictGenericChecks 
- noUnusedLocals 

- -noUnusedParameters 

-— out- 


--outDir 
--outFile 


paths [2] 


--preserveConstEnums 


string 


number 


string 


string 


string 

boolean 
boolean 
boolean 
boolean 
boolean 
boolean 
boolean 
boolean 
boolean 
boolean 
boolean 
boolean 
boolean 
boolean 
string 


string 
string 


Object 


boolean 


0 

target === "ES6" ' 
"ES6" : "commonjs" 
module --- "AMD" 


"System" or "ES6" 


"Classic" : "Node" 
(platform specific) 

false 

false 

false 

false 

false 

false 

false 

false 

false 

false 

false 

false 

false 


false 


false 


--preserveSymlinks 
--preserveWatchOutput 
--pretty [1] 


--project 
-p 


--reactNamespace 


--removeComments 


--rootDir 


rootDirs [2] 


--skipDefaultLibCheck 
--SkipLibCheck 


- sourceMap 


--sourceRoot 


--strict 


--strictFunctionTypes 


--strictPropertyInitialization 


--strictNullChecks 


--stripInternal [1] 


suppressExcessPropertyErrors [1] 


suppressImplicitAnyIndexErrors 


--target 
-t 


--traceResolution 


boolean false 
boolean false 
boolean false 
string 

string "React" 
boolean false 


(common root director 


string computed from the lisi 
input files) 
string[] 
boolean false 
boolean false 
boolean false 
string 
boolean false 
boolean false 
boolean false 
boolean false 
boolean false 
boolean false 
boolean false 
string "ES3" 
boolean false 


--types string[ ] 


--typeRoots string[] 

--version 

-V 

--watch 

-W 

o [1] 这 些 选项 是 试验 性 的 。 

o Pl 这 些 选项 只 能 在 tsconfig.json 里 使 用 ， 不 能 在 命令 行使 用 。 


e 在 tsconfig.json 文件 里 设置 编译 器 选项 。 
e 在 MSBuild 工 程 里 设置 编译 器 选项 。 


概述 


编译 选项 可 以 在 使 用 MSBuild 的 项 目 里 通过 MSBuild 属 性 指定 。 


| F 


<PropertyGroup Condition="'$(Configuration)' == 'Debug'"> 
<TypeScriptRemoveComments>false</TypeScriptRemoveComments> 
<TypeScriptSourceMap>true</TypeScriptSourceMap> 


</PropertyGroup> 


«PropertyGroup Condition="'$(Configuration)' == 'Release'"> 
<TypeScriptRemoveComments>true</TypeScriptRemoveComments> 
<TypeScriptSourceMap>false</TypeScriptSourceMap> 


</PropertyGroup> 
<Import 


Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio 
\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets" 


Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\Vi 
sualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScri 


Di targets: /> 


E SB 


映射 


编译 选项 
--allowJs 
--allowSyntheticDefaultImports 
- -allowUnreachableCode 
- allowUnusedLabels 
--alwaysStrict 
- -baseUrl 


--charset 


MSBuild & 1€ £ 4% 
MSBuild 不 支持 此 选项 
TypeScriptAllowSyntheticDefaultlmpo 
TypeScriptAllowUnreachableCode 
TypeScriptAllowUnusedLabels 
TypeScriptAlwaysStrict 
TypeScriptBaseUrl 
TypeScriptCharset 


--declaration 
--declarationDir 
--diagnostics 
--disableSizeLimit 

- -emitBOM 
--emitDecoratorMetadata 
--experimentalAsyncFunctions 


--experimentalDecorators 


forceConsistentCasingInFileNames 
- -help 
--importHelpers 
- -inlineSourceMap 
- -inlineSources 
--init 
--isolatedModules 
--jsx 
--jsxFactory 
--lib 
--listEmittedFiles 
--listFiles 
--locale 
--mapRoot 
- -maxNodeModuleJsDepth 
--module 
--moduleResolution 
- -newLine 
- -noEmit 
--noEmitHelpers 


--noEmitOnError 


TypeScriptGeneratesDeclarations 
TypeScriptDeclarationDir 

MSBuild 不 支持 此 选项 

MSBuild 不 支持 此 选项 
TypeScriptEmitBOM 
TypeScriptEmitDecoratorMetadata 
TypeScriptExperimentalAsyncFunctio 


TypeScriptExperimentalDecorators 
TypeScriptForceConsistentCasingInF 


MSBuild 不 支持 此 选项 
TypeScriptlmportHelpers 
TypeScriptlnlineSourceMap 
TypeScriptlnlineSources 
MSBuild 不 支持 此 选项 
TypeScriptlsolatedModules 
TypeScriptJSXEmit 
TypeScriptJSXFactory 
TypeScriptLib 

MSBuild 不 支持 此 选项 
MSBuild 不 支持 此 选项 
automatic 
TypeScriptMapRoot 
MSBuild 不 支持 此 选项 
TypeScriptModuleKind 
TypeScriptModuleResolution 
TypeScriptNewLine 
MSBuild 不 支持 此 选项 
TypeScriptNoEmitHelpers 
TypeScriptNoEmitOnError 


--noFallthroughCasesInSwitch TypeScriptNoFallthroughCasesInSwit 


- -noImplicitAny TypeScriptNolmplicitAny 
--noImplicitReturns TypeScriptNolmplicitReturns 
--noImplicitThis TypeScriptNolmplicitThis 
--noImplicitUseStrict TypeScriptNolmplicitUseStrict 
--noStrictGenericChecks TypeScriptNoStrictGenericChecks 
- noUnusedLocals TypeScriptNoUnusedLocals 

- -noUnusedParameters TypeScriptNoUnusedParameters 
--noLib TypeScriptNoLib 

--noResolve TypeScriptNoResolve 

--out TypeScriptOutFile 

--outDir TypeScriptOutDir 

--outFile TypeScriptOutFile 

--paths MSBuild 不 支持 此 选项 
--preserveConstEnums TypeScriptPreserveConstEnums 
- -preserveSymlinks TypeScriptPreserveSymlinks 

- -listEmittedFiles MSBuild 不 支持 此 选项 

--pretty MSBuild 不 支持 此 选项 
--reactNamespace TypeScriptReactNamespace 
--removeComments TypeScriptRemoveComments 
--rootDir TypeScriptRootDir 

--rootDirs MSBuild 不 支持 此 选项 
--skipLibCheck TypeScriptSkipLibCheck 
--skipDefaultLibCheck TypeScriptSkipDefaultLibCheck 
--sourceMap TypeScriptSourceMap 
--sourceRoot TypeScriptSourceRoot 

--strict TypeScriptStrict 
--strictFunctionTypes TypeScriptStrictFunctionTypes 
--strictNullChecks TypeScriptStrictNullChecks 


--stripInternal TypeScriptStripInternal 


--suppressExcessPropertyErrors TypeScriptSuppressExcessPropertyE 


suppressImplicitAnyIndexErrors TypeScriptSuppresslmplicitAnyIndext 


--target TypeScriptTarget 
--traceResolution MSBuild % x. 4% sexe 9f 
--types MSBuild F x. 4% 96.3 7H 
--typeRoots MSBuild F x. 4% 963 7H 
--watch MSBuild 不 支持 此 选项 
MSBuild only option TypeScriptAdditionalFlags 


KAS Jt] £9 Visual Studio 版 本 里 支持 哪些 选项 ? 


查找 C:\Program Files 

(x86) \MSBuild\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScr 
iptMMicrosoft.TypeScript.targets 文件 。 可 用 的 MSBuild XML 标签 与 相应 
的 tsc 编译 选项 的 映射 都 在 那里 。 


ToolsVersion 


工程 文件 里 的 <TypeScriptToolsVersion>1.7</TypeScriptToolsVersion> & 
性 值 表 明了 构建 时 使 用 的 编译 器 的 版 本 号 (这 个 例子 里 是 1.7) 这 样 就 允许 一 个 工 
程 在 不 同 的 机 器 上 使 用 相同 版 本 的 编译 器 进行 构建 。 


如 果 没 有 指定 TypeScriptToolsVersion ， 则 会 使 用 机 器 上 安装 的 最 新 版 本 的 编 


译 器 去 构建 。 


如 果 用 户 使 用 的 是 更 新 版 本 的 TypeScript， 则 会 在 首次 加 载 工程 的 时 候 看 到 一 个 提 
示 升 级 工程 的 对 话 框 。 


TypeScriptCompileBlocked 


如 果 你 使 用 其 它 的 构建 工具 (rete > gulp’ grunts) 并 且 使 用 VS 做 为 开发 和 调 
斌 工具， 那么 在 工程 里 设 

置 <TypeScriptCompileBlocked>true</TypeScriptCompileBlocked> 。 这 样 
VS 只 会 提供 给 你 编辑 的 功能 ， 而 不 会 在 你 按 F5 的 时 候 去 构建 。 


在 MSBuild 里 使 用 编译 选项 
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Build tools 


e Browserify 
e Duo 

e Grunt 

e Gulp 

e Jspm 

e Webpack 
e MSBuild 
e NuGet 


Browserify 


BR 


npm install tsify 


使 用 命令 行 交互 


browserify main.ts -p [ tsify --noImplicitAny ] > bundle.js 


使 用 API 


var browserify = require("browserify"); 
var tsify = require("tsify"); 


browserify() 
.add('main.ts') 
.plugin('tsify', { noImplicitAny: true }) 
.bundle() 
.pipe(process.stdout); 


更 多 详细 信息 : smrqltsify 


Duo 


BR 


npm install duo-typescript 


使 用 命令 行 交互 


duo --use duo-typescript entry.ts 


使 用 API 


var Duo = require('duo'); 

var fs = require('fs') 

var path = require('path') 

var typescript = require('duo-typescript'); 


var out = path.join(__dirname, "output.js") 


Duo(__ dirname) 
.entry('entry.ts') 
.use(typescript()) 
.run( function (err, results) ( 
if (err) throw err; 
// Write compiled result to output file 
fs.writeFileSync(out, results.code); 


3): 


更 多 详细 信息 : frankwallis/duo-typescript 


Grunt 


BR 


npm install grunt-ts 


X 4 Gruntfile.js 


module.exports = function(grunt) { 
grunt.initConfig(1 


[gt 
default : { 
src: pss ts. “inode modules/**7*.ts' | 
} 
} 


}); 
grunt.loadNpmTasks("grunt-ts"); 


grunt.registerTask("default", ["ts"]); 
u 


更 多 详细 信息 : TypeStrong/grunt-ts 


Gulp 


` 


ae 
AX 


^ 


npm install gulp-typescript 


A Agulpfile.js 


var gulp = require("gulp"); 
var ts = require("gulp-typescript"); 


gulp.task("default", function () { 


var tsResult = gulp.src("src/*.ts") 


-pipe(ts({ 
noImplicitAny: true, 
out: "output.js" 


})); 


return tsResult.js.pipe(gulp.dest('built/local')); 


}); 
更 多 详细 信息 : ivogabe/gulp-typescript 


Jspm 


` 


ae 
AX 


^ 


npm install -g jspmQbeta 


注意 : 目前 jspm 的 0.16beta 版 本 支持 TypeScript 


更 多 详细 信息 : TypeScriptSamples/jspm 


Webpack 


BR 


npm install ts-loader --save-dev 


A Awebpack.config.js 


module.exports = { 


entry: "./src/index.tsx", 

output: { 
filename: "bundle.js" 

ty 

resolve: { 
// Add '.ts' and '.tsx' as a resolvable extension. 
extensions: ["", ".webpack.js", ".web.js", ".ts", ".tsx" 

vods] 
tr 
module: { 


loaders: [ 
// all files with a '.ts' or '.tsx' extension will b 
e handled by 'ts-loader' 
{ test: /\.tsx?$/, loader: "ts-loader" } 


e 


查看 更 多 关于 ts-loader 的 详细 信息 
或 者 


e awesome-typescript-loader 


MSBuild 


更 新 工程 文件 ， 包 含 本 地 安装 的 Microsoft.TypeScript.Default.props (在 顶 
端 ) 和 Microsoft.TypeScript.targets (在 底部 ) 文件 : 


与 其 它 构建 工具 整合 


<?xml version="1.0" encoding="utf-8"?> 
<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http:/ 
/schemas.microsoft.com/developer/msbuild/2003"» 
<!-- Include default props at the top --> 
«Import 
Project-'"$(MSBuildExtensionsPath32)MMicrosoftNVisualStudio 
\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.Default 
. props" 
Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\Vi 
sualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScri 
pt.Default.props')" /> 


<!-- TypeScript configurations go here --> 

<PropertyGroup Condition="'$(Configuration)' == 'Debug'"> 
<TypeScriptRemoveComments>false</TypeScriptRemoveComments> 
<TypeScriptSourceMap>true</TypeScriptSourceMap> 

</PropertyGroup> 

«PropertyGroup Condition="'$(Configuration)' == 'Release'"> 
<TypeScriptRemoveComments>true</TypeScriptRemoveComments> 
<TypeScriptSourceMap>false</TypeScriptSourceMap> 

</PropertyGroup> 


<!-- Include default targets at the bottom --> 
<Import 
Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio 
\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets" 


Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\Vi 
sualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScri 
pt.targets')" /> 
</Project> 


|) 


关于 配置 MSBuild 编 译 器 选项 的 更 多 详细 信息 ， 请 参考 : 在 MSBuild 里 使 用 编译 选 
项 


NuGet 
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e 右键 点 击 -> Manage NuGet Packages 
e 查找 Microsoft.TypeScript.MSBuild 
e 点 击 Install 

安装 完成 后 ，Rebuild 。 


更 多 详细 信息 请 参考 Package Manager Dialog 和 using nightly builds with NuGet 


在 太平 洋 标准 时 间 每 天 午夜 会 自动 构建 TypeScript 的 master 分 支 代码 并 发 布 到 
NPM 和 NuGet 上 。 下 面 将 介绍 如 何 获得 并 在 工具 里 使 用 它们 。 


使 用 npm 


npm install -g typescript@next 


使 用 NuGet 和 MSBuild 
注意 : 你 需要 配置 工程 来 使 用 NuGet 包 。 详细 信息 参考 配置 MSBuild 工 程 来 使 
用 NuGet 。 

www.myget.org ° 

有 两 个 包 : 


e Microsoft.TypeScript.Compiler : 仅 包含 工具 


( tsc.exe * lib.d.ts ， 等 。) 。 
e Microsoft.TypeScript.MSBuild :和 上 面 一 样 的 工具 ， 还 有 MSBuild 的 任务 


和 目标 
( Microsoft.TypeScript.targets ， Microsoft.TypeScript.Default.pr 


ops ， 等 。) 


更 新 IDE 来 使 用 每 日 构建 


你 还 可 以 配置 IDE 来 使 用 每 日 构建 。 首先 你 要 通过 npm 安 装 包 。 你 可 以 进行 全 局 安 
装 或 者 安装 到 本 地 的 node_modules 目录 下 。 


安 
下 面 的 步骤 里 我 们 假设 你 已 经 安装 好 了 typescript@next ° 


Visual Studio Code 


更 新 .vscode/settings.json 如 下 : 


"typescript.tsdk": "<path to your folder>/node_modules/typescrip 
talib" 


详细 信息 参见 VSCode 文 档 。 
Sublime Text 
更 新 Settings - User 如 下 : 


"typescript tsdk": "«path to your folder>/node_modules/typescrip 
t1 


详细 信息 参见 如 何在 Sublime Text €. 3c X TypeScript4& t# » 


Visual Studio 2013 and 2015 
注意 : 大 多 数 的 改变 不 需要 你 安装 新 版 本 的 VS TypeScriptis + » 


当前 的 每 日 构建 不 包含 完整 的 插件 安装 包 ， 但 是 我 们 正在 试 着 提供 每 日 构建 的 安装 


1. 下 载 VSDevMode.ps1 脚 本 。 
参考 wiki 文档 : 使 用 自 定 义 语 言 服务 文件 。 
2. 在 PowerShell 命 令 行 窗口 里 执行 : 


VS 2015 : 


VSDevMode.psi 14 -tsScript «path to your folder>/node_module 
s/typescript/lib 


VS 2013 : 


VSDevMode.psi 12 -tsScript «path to your folder»/node module 
s/typescript/lib 


IntelliJ IDEA (Mac) 


前 往 Preferences > Languages & Frameworks > TypeScript 


TypeScript Version: 4» X 38 3d NPM 


br 


* : /usr/local/lib/node modules/typescript/lib 


Table of Contents 


e TypeScript € “this 

e 编码 规范 

e 常见 编译 错误 

e 支持 TypeScript 的 编辑 器 

e 结合 ASPNET v51& M TypeScript 
e AL 

e 发 展 路 线 图 


4& JavaScript € (2A TypeScript) > this 关键 字 的 行为 与 其 它 语言 相 比 大 为 不 
同 。 这 可 能 会 很 邻 人 吃惊 ， 特 别 是 对 于 那些 使 用 其 它 语言 的 用 户 ， 他 们 凭借 其 直觉 
来 想象 this 关键 字 的 行为 。 


这 篇 文章 会 教 你 怎么 识别 及 调试 TypeScript 里 的 this 问题， 并 且 提 供 了 一 些 解决 
Z f$ 4BUT 。 


典型 症状 和 危险 系数 


丢失 this 上 下 文 的 典型 症状 包括 : 


e 类 的 某 字段 ( this.foo ) 为 undefined ， 但 其 它 值 没有 问题 

e this 的 值 指向 全 局 的 window 对 象 而 不 是 类 实例 对 象 〈 在 非 严 格 模式 下 ) 

e this 的 值 为 undefined 而 不 是 类 实例 对 象 (严格 模式 下 ) 

e 调用 类 方法 ( this.doBa() ) 失败 ， 错 误 信 息 如 “TypeError: undefined is not 
a function” > “Object doesn't support property or method 'doBar” 或 “this.doBar 
is not a function” 


程序 中 应 该 出 现 了 以 下 代码 : 


e 事件 监听 ， 比 如 window.addEventListener('click', 
myClass.doThing); 
e Promise 解 决 ， 比 如 myPromise.then(myClass.theNextThing); 
e 第 三 方 库 回 调 ， 比 如 $(document).ready(myClass.start); 
e AAE > et someArray.map(myClass.convert) 
ViewModel 类 型 的 库 里 的 类 ， 比 如 «div data-bind="click: 
myClass.doSomething"> 
可 选 包 里 的 函数 ， 比 如 $.ajax(url, { success: myClass.handleData }) 


JavaScript 里 的 this 究竟 是 什么 ? 


已 经 有 大 量 的 文章 讲述 了 JavaScript 里 this 关键 字 的 危险 性 。 查 看 这 里 ， 这 里 ， 
或 这 里 。 


当 JavaScript 里 的 一 个 函数 被 调用 时 ， 你 可 以 按照 下 面 的 顺序 来 推断 出 this 指向 
的 是 什么 (这 些 规则 是 按 优先 级 顺序 排列 的 ) 


e 如 果 这 个 函数 是 functionzbind 调用 的 结果 ， 那 么 this 指向 的 是 传 
入 bind 的 参数 

e wR HRV foo.func() 形式 调用 的 ， 那 么 this 值 为 foo 

e 如 果 是 在 严格 模式 下 ， this 将 为 undefined 

e FI> this 将 是 全 局 对 象 〈 浏 览 器 环境 里 为 window ) 


这 些 规则 会 产生 与 直觉 相反 的 效果 。 比 如 : 
class Foo { 
x = 3: 


print() ( 
console.log('x is ' + this.x); 


var f - new Foo(); 
f.print(); // Prints 'x is 3' as expected 


// Use the class method in an object literal 
var z = { x: 10, p: f-praint }; 
ZoD Or 77^ Prints: 619 10^ 


var p = Z.p; 
p(); // Prints 'x is undefined' 


this 的 危险 信号 


你 要 注意 的 最 大 的 危险 信号 是 在 要 使 用 类 的 方法 时 没有 立即 调用 它 。 任 何 时 候 你 看 
到 类 方法 被 引用 了 却 没 有 使 用 相同 的 表达 式 来 调用 时 ， this 可 能 已 经 不 对 了 。 


例子 : 


var X = new MyObject(); 
x.printThing(); // SAFE, method is invoked where it is referenced 


var y = X.printThing; // DANGER, invoking 'y()' may not have cor 
rect 'this' 


window.addEventListener('click', x.printThing, 10); // DANGER, m 
ethod is not invoked where it is referenced 


window.addEventListener('click', () => x.printThing(), 10); // S 
AFE, method is invoked in the same expression 


Bnm——————————————————n Án Fi 
修复 


可 以 通过 一 些 方法 来 保持 this 的 上 下 文 。 


使 用 实例 郊 数 
代替 TypeScript 里 默认 的 原型 方法 ， 你 可 以 使 用 一 个 实例 匡 头 函数 来 定义 类 成 员 : 


class MyClass { 
private status = "blah"; 


public run = () => { // <-- note syntax here 
alert(this.status); 


} 


var x = new MyClass(); 
$(document).ready(x.run); // SAFE, 'run' will always have correc 
t 'this' 


ires n heel plies 。 如 果 这 个 方法 通常 是 

常 调用 的 ， 那 么 这 么 做 有 点 。 然 而 ， 它 经 常会 在 回调 函数 里 调用 ， 让 类 
实例 捕获 到 this E TEE m 包 来 得 更 有 效率 一 
此 


Da 


e 好 :其 它 外 部 使 用 者 不 可 能 忘记 处 理 this 上 下 文 

e 好 :在 TypeScript 里 是 类 型 安全 的 

e 好 : 如 果 函 数 带 参 数 不 需要 额外 的 工作 

e Io 派生 类 不 能 通过 使 用 super 调用 基 类 方法 

e 坏 :在 类 与 用 户 之 前 产生 了 额外 的 非 类 型 安全 的 约束 : 明确 了 哪些 方法 提前 线 
定 了 以 及 哪些 没有 


本 地 的 胖 箭 头 


在 TypeScrip 里 (这 里 为 了 讲解 添加 了 一 些 参数 ) 


var x = new SomeClass(); 
someCallback((n, m) => x.doSomething(n, m)); 


e 好 与 坏 : ABH ES HE erue 
e 好 :在 TypeScript，100% 的 类 型 安 

e 好 :在 ECMAScript 3 里 同样 生效 

e 好 :你 只 需要 输入 一 次 实例 名 

e HK: 你 要 输出 2 次 参数 名 

e 坏 : 对 于 可 变 参 数 不 起 作用 ('rest') 


Function.bind 


var x = new SomeClass(); 

// SAFE: Functions created from function.bind are always preserv 
e “this” 

window.setTimeout(x.someMethod.bind(x), 100); 


e 好 与 坏 : ke E) E a BAAR 
e 好 : 如 果 函 数 带 参数 不 需要 额外 的 工作 

e HK: 目前 在 TypeScript 里 ， 不 是 类 型 安全 的 

e. 坏 : 只 在 ECMAScript 5 里 生效 

e 坏 : 你 要 输入 2 次 实例 名 


TypeScript € &jthis 
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这 个 编码 规范 是 给 TypeScript 开 发 团队 在 开发 TypeScript 时 使 用 的 。 对 于 使 用 
TypeScript 的 普通 用 户 来 说 不 一 定 适用 ， 但 是 可 以 做 为 一 个 参考 。 


命名 


1. 使 用 PascalCase 为 类 型 命名 。 

2. 不 要 使 用 I 做 为 接口 名 前 级 。 

3. 使 用 PascalCase 为 枚 举 值 命名 。 

4. 使 用 camelCase 为 函数 命名 。 

5. 使 用 camelCase 为 属性 或 本 地 变量 命名 。 
6. 不 要 为 私有 属性 名 添加 Wie 

7. 尽 可 能 使 用 完整 的 单词 拼写 命名 。 


组 件 


1. 1 个 文件 对 应 一 个 逻辑 组 件 (比如 : 解析 器 ， 检 查 器 ) 。 
2. 不 要 添加 新 的 文件 。 :) 
3. .generated.* 后 级 的 文件 是 自动 生成 的 ， 不 要 手动 改 它 。 


类 型 

不 要 导出 类 型 / 兄 数 ， 除 非 你 要 在 不 同 的 组 件 中 共享 它 。 
. 不 要 在 全 局 命名 空间 内 定义 类 型 / 值 。 
共享 的 类 型 应 该 在 types.ts 里 定义 。 

. 在 一 个 文件 里 ， 类 型 定义 应 该 出 现在 顶部 。 


A ON = 


null 和 undefined 
1. 使 用 undefined > 75 4% M null ° 
一 般 假设 


1. 假设 像 Nodes，Symbols 等 这 样 的 对 象 在 定义 它 的 组 件 外 部 是 不 可 改变 的 。 不 
要 去 改变 它们 。 


2. 假设 数组 是 不 能 改变 的 。 


yx 


1. 为 了 保持 一 致 ， 在 核心 编译 链 中 不 要 使 用 类 ， 使 用 部 数 闭 包 代替 。 


标记 


1. 一 个 类 型 中 有 超过 2 个 布尔 属性 时 ， 把 它 变 成 一 个 标记 。 


注释 


为 函数 ， 接 口 ， 枚 举 类 型 和 类 使 用 JSDoc 风 格 的 注释 。 


字符 串 


1. 使 用 双 引 号 "" 
2. 所 有 要 展示 给 用 户 看 的 信息 字符 串 都 要 做 好 本 地 化 工作 (在 
diagnosticMessages.json 中 创建 新 的 实体 ) 。 


错误 提示 信息 

. 在 句子 结尾 使 用 ，。 

.对 不 确定 的 实体 使 用 不 定 冠 词 。 

.确切 的 实体 应 该 使 用 名 字 (变量 名 ， 类 型 名 等 ) 

当 创建 一 条 新 的 规则 时 ， 主 题 应 该 使 用 单数 形式 (比如 : An external module 
cannot... 而 不 是 External modules cannot) 。 

5. 使 用 现在 时 态 。 


BONG 


错误 提示 信息 代码 


提示 信息 被 划分 类 成 了 一 般 的 区 间 。 如 果 要 新 加 一 个 提示 信息 ， 在 上 条 代码 上 加 1 
做 为 新 的 代码 。 


e 1000 语法 信息 

e 2000 语言 信息 

e 4000 声明 生成 信息 
e 5000 编译 器 选项 信息 
e 6000 命令 行 编译 器 信息 
e 7000 nolmplicitAny 信 息 


普通 方法 
由 于 种 种 原因 ， 我 们 避免 使 用 一 些 方法 ， 而 使 用 我 们 自己 定义 的 。 


1. 不 使 用 ECMAScript 582k ; 而 是 使 用 core.ts 这 里 的 。 

2. 不 要 使 用 for..in 语句 ; 而 是 使 
用 ts.forEach > ts.forEachKey 和 ts.forEachValue 。 注 意 它 们 之 间 
的 区 别 。 

3. 如 果 可 能 的 话 ， 党 试 使 用 ts.forEach > ts.map 和 ts.filter 代替 特 
IR e 


风格 


1. 1% Jf arrow RFE S RARAN © 
2. AX € X83 N17 Jearrow Har 8 4 X438 3 © 
比如 ， (x) => x + x 是 错误 的 ， 下 面 是 正确 的 做 法 : 


L X 
li. (x,y) == x+y 
ii. <T>(x: T, y: T) => x === y 
3. 总 是 使 用 {} 把 循环 体 和 条 件 语句 括 起 来 。 
4. 开始 的 { 总 是 在 同一 行 。 
5. 小 括号 里 开始 不 要 有 空白 . 
过 号 ， 冒号， 分 号 后 要 有 一 个 空格 。 比 如 : 


ko 


i for (var i = 0, n = str. length? i < 10; i++) { } 
i aeaeo 
iii. function f(x: number, y: string): void { } 


6. 每 个 变量 声明 语句 只 声明 一 个 变量 


(比如 使 用 var x = 1; var y = 2; 


7. else 要 在 结束 的 后 另 起 一 行 。 


而 不 是 var x 


下 面 列 出 了 一 些 在 使 用 TypeScript 语 言 和 编译 器 过 程 中 常见 的 容易 让 人 感到 困惑 的 


错 误 信 息 。 


AANA RA 的 常 WES dX 


"tsc.exe" exited with error code 1 
修复 : 

e 检查 文件 编码 ， 确 保 为 UTF-8 - https://typescript.codeplex.com/workitem/1587 
external module XYZ cannot be resolved 


修复 : 


e 检查 模块 路 径 是 否 大 小 写 敏 感 - https://typescript.codeplex.com/workitem/2134 


快捷 列表 


e Atom 

e Eclipse 

e Emacs 

e NetBeans 

e Sublime Text 

e TypeScript Builder 
e Vim 

e Visual Studio 

e Visual Studio Code 
e WebStorm 


Atom 


Atom-TypeScript > & TypeStrong# X 49 4t Atom 49 TypeScripti$ & IRF » 


Eclipse 


Eclipse TypeScript 插件 ， 由 Palantir 开 发 的 Eclipse 插件 。 


Emacs 


tide - TypeScript Interactive Development Environment for Emacs 


NetBeans 


e nbts - NetBeans TypeScript editor plugin 
e Geertjan's TypeScript NetBeans Plugin 


Sublime Text 


Sublime 4 TypeScriptd& fF > "T v23% i Package Control X > X4*Sublime Text 2 
fe Sublime Text 3. 


TypeScript Builder 


TypeScript Builder * TypeScript fl] IDE. 
Vim 
BER 


显示 ,ts 和 .d.ts ° 


e leafgarland/typescript-vim 提 供 了 语法 文件 用 来 高 
高 完 和 DOM 关 键 字 。 


5 
e HerringtonDarkholme/yats.vim 提 供 了 更 多 语法 高 亮 
语言 服务 工具 
有 两 个 主要 的 TypeScript 插 件 : 


e Quramy/tsuquyomi 

e clausreinke/typescript-tools.vim 
如 果 你 想 要 输出 时 自动 补 全 功能 ， 你 可 以 安装 YouCompleteMe 并 添加 以 下 代码 
到 .vimrc 里 ， 以 指定 哪些 符号 能 用 来 触发 补 全 功能 。YouCompleteMe 会 调用 它 
们 各 自 TypeScript 插 件 来 进行 语义 查询 。 


if !exists("g:ycm_semantic_triggers") 
let g:ycm_semantic_triggers = {} 
endif 
let g:ycm semantic triggers['typescript'] = ['.'] 


Visual Studio 2013/2015 


Visual Studio €. X Microsoft Web Tools #t 7 J TypeScript ° 


TypeScript for Visual Studio 2015 在 这 里 


TypeScript for Visual Studio 2013 在 这 里 


Visual Studio Code 


Visual Studio Code， 是 一 个 轻 量 级 的 跨 平 台 编辑 器 ， 内 置 了 对 TypeScript 的 支持 。 


Webstorm 


WebStorm， 同 其 它 JetBrains IDEs 一 样 ， 直 接 包含 了 对 TypeScript 的 支持 。 


5 ASP.NET v5 一 起 使 用 TypeScript 需 要 你 用 特定 的 方式 来 设置 你 的 工程 。 更 多 关 


于 ASP.NET v5 的 详细 信息 请 查看 ASP.NET v5 文档 在 Visual Studio 的 工程 里 支持 当 
， 可 以 在 这 


前 的 tsconfig.json 还 在 开发 之 中 ， 


工程 设置 


文 里 查看 进 


度 #3983 ° 


我 们 就 以 在 Visual Studio 2015 里 创建 一 个 空 的 ASPNET v5 工 程 开 始 ， 如 果 你 对 


ASP.NET v5 还 不 熟悉 ， 可 以 查看 这 


New ASP.NET Project - HelloTypeScript 


Select a template: 





ASP.NET 4.6 Templates 
=, 4 4 a 
Ss E ff mil 
Empty Web Forms MVC Web API 
4 cs 
= 
o e- 
Azure API App Azure Mobile 
(Preview) Service 
ASP.NET 5 Preview Templates 
5 5 
m Li 
Web API Web 
Application 
Add folders and core references for: 
Web Forms MVC Web API 


Add unit tests 


Test project name: — HelloTypeScript.Tests 


个 教程 。 


mi 
oul 
Single Page 
Application 


PREVIEW - An empty project template for creating 
ASP.NET 5 application. This template does not have any 
content in it. 


Learn more 


Change Authentication 


Authentication: No Authentication 
© Microsoft Azure 
(a) [ ] Host in the cloud 


Web App v 





(oc) [ea 


i 





然后 在 工程 根 目 录 下 添加 一 个 scripts 目录 。 


件 和 tsconfig.json 文件 来 设置 
样 才 能 正 


择 Add ， New Item 


编译 选 


这 就 是 我 们 将 要 添加 TypeScript 文 
先 项 的 地 方 。 请 注意 目录 名 和 路 径 都 必须 这 
常 工作 。 添加 tsconfig.json 文件 ， 右 键 点 击 scripts 目录 ， 选 

° Æ Client-side 下 ， 


你 能 够 找到 它 ， 如 下 所 示 。 


24 ASP.NET v5 使 用 TypeScript 














Add New ltem - HelloTypeScript ? x 
4 Installed Sort by: Default «| GF Search Installed Templates (Ctrl+ 日 P~- 
Seaver side [3 HTML Page Client-side Type: Client-side 
Client-side e : 
P JSON configuration file for the TypeScript 
> Online EJ JavascriptFile Client-side compiler 
Style Sheet Client-side 
二 TS - | e - 
=| TypeScript File Client-side 
TypeScript JSON Configuration File 
6 ] Bower Configuration File Client-side 
6 ] NPM configuration file Client-side 
Js 
EN Gulp Configuration file Client-side 
Cf sun cont 
EN Grunt Configuration file Client-side 
6 ] JSON File Client-side 
6 ] JSON Schema File Client-side 
JS 
JSX File Client-side 
<a> 
C HORS CER NEG at IY 
Click here to go online and find templates. 
Name: tsconfigl.json 
Add Cancel 








Solution Explorer 


oo0G|o-Ss85m^4- 
Search Solution Explorer (Ctrl+;) 


fg] Solution 'HelloTypeScript' (1 project) 
4 — Solution Items 
£T global.json 
4 ‘ql stc 
4 HelloTypeScript 
Jf Properties 
a References 
®@ wwwroot 
^ Dependencies 
后 | scripts 
TS app.ts 


£T tsconfig.json 
à hosting.ini 
b £T projectjson 
of) Project Readme.html 
c* Startup.cs 


Solution Explorer BEETuESTI EC 
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最 后 我 们 还 要 将 下 面 的 选项 添加 到 tsconfig.json 文件 
的 "compilerOptions" 节点 里 ， 让 编译 器 输出 重 定向 到 wwwroot CHK: 


"outDir": "../wwwroot/" 


下 面 是 配置 好 tsconfig.json 后 可 能 的 样子 


"compilerOptions": f 
"noImplicitAny": false, 
"noEmitOnError": true, 
"removeComments": false, 
"sourceMap": true, 
"target": "esb5", 
"outDir"s ' — /wwWwWrOOt'" 


现在 如 果 我 们 构建 这 个 工程 ， 你 就 会 注意 到 app.js 和 app.js.map 文件 被 创建 
在 wwwroot 目录 里 。 


Z5 ASP.NET v5 使 用 TypeScript 


@\e-saals— 
Search Solution Explorer (Ctrl+;) 


网 Solution 'HelloTypeScript' (1 project) 
4 | Solution Items 
£T global.json 
4 mi src 
4 [5] HelloTypeScript 
JF Properties 
b =m References 
4 & wwwroot 
4 LJ appjs 
Ù appjs.map 
^ Dependencies 
| scripts 
TS app.ts 
£T tsconfig.json 
à hosting.ini 
£T project.json 
13) Project Readme.html 
C* Startup.cs 


Solution Explorer MES T ME ETATIS 





工程 与 虚拟 工程 


当 添 加 了 一 个 tsconfig.json 文件 ， 你 要 明白 很 重要 的 一 点 是 我 们 创建 了 一 个 虚 
拟 TypeScript 工 程 ， 在 包含 tsconfig.json 文件 的 目录 下 。 被 当 作 这 个 虚拟 工程 
一 部 分 的 TypeScript 文 件 是 不 会 在 保存 的 时 候 编 译 的 。 在 包含 tsconfig.json X 
件 的 目录 外 层 里 存在 的 TypeScript 文 件 不 会 被 当 作 虚拟 工程 的 一 部 分 。 下 图 中 ， 可 
以 见 到 这 个 虚拟 工程 ， 在 红色 矩形 里 。 
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Z5 ASP.NET v5 使 用 TypeScript 





Solution Explorer 
全 oO-- H0 Fi 
Search Solution Explorer (Ctrl+;) p- 





网 Solution 'HelloTypeScript' (1 project) 
4 & Solution Items 
£T global.json 
4 mi sic 
4 HelloTypeScript 
JF Properties 
b =m References 
4 & wwwroot 
4 LJ appjs 
t) appjs.map 
^ Dependencies 
4 ix Code 
TS outsideVirtualProject.ts 
4 | scripts 
TS app.ts 


£T tsconfig.json 





&1 hosting.ini 
b £T projectjson 

L3 Project Readme.html 

C* Startup.cs 


保存 时 编译 


想 要 局 用 ASPNET v5 项 目的 保存 时 编译 功能 ， 你 必须 为 不 是 虚拟 TypeScript 工 程 一 
部 分 的 TypeScript 文 件 启 用 保存 时 编译 功能 。 如 果 工 程 里 存在 tsconfig.json X 


件 ， 那 么 模块 类 型 选项 的 设置 会 被 忽略 。 
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Options ? x 


Search Options (Ctrl-E) p Virtual Projects in Solution Explorer 
Display Virtual Projects when no Solution is loaded 


[C] Display Virtual Projects when a Solution is loaded 





c+ 

C/C++ 
CoffeeScript 
css 

HTML z zm 

HTML (Web Forms) © Use CommonJS code generation for modules that are not part of a project 
JavaScript © Use UMD code generation for modules that are not part of a project 


m © Use System code generation for modules that are not part of a project 


Plain Text ECMAScript version for files that are not part of a project 


vv 


Compile on Save 





PowerShell 
ResJSON Resource 
SCSS 


© ECMAScript 3 
@ ECMAScript 5 
© ECMAScript 6 


SOL Server Tools 

T-SQL90 

TypeScript 
General 
Scroll Bars 
Tabs 

b Formatting 

4 Project 


b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
b 
4 











mA 
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架构 概述 


层次 概述 


VS Managed 





VS Shim tsserver 
(shims.ts) (server.ts) 
Language Service Standalone TS Compiler 
(services.ts) (tsc.ts) 


Core TypeScript Compiler 


(core.ts, program.ts, scanner.ts, parser.ts, checker.ts, emitter.ts) 





e Ji STypeScript% iz 4 


o 语法 分 析 器 (Parser) : 以 一 系列 原文 件 开始 , 根据 语言 的 语法 , 生成 抽 
象 语 法 树 (AST) 


o 联合 器 (Binder) : 使 用 一 个 Symbol 将 针对 相同 结构 的 声明 联合 在 一 
起 (例如 : 同一 个 接口 或 模块 的 不 同 声明 ， 或 拥有 相同 名 字 的 函数 和 模 
JR) 。 这 能 帮助 类 型 系统 推导 出 这 些 具名 的 声明 。 


o ee 与 检查 器 (Type resolver / Checker) : 解析 每 种 类 型 的 构 
， 检查 读 写 语义 并 生成 适当 的 诊断 信息 。 


o 生成 器 (Emitter) : 从 一 系列 输入 文件 ( .ts 和.d.ts) 生成 输出 ， 它 们 可 
以 是 以 下 形式 之 一 : JavaScript (js) ， 声 明 (.d.ts) ， 或 者 是 source 
maps (.js.map) ° 


o 预 处 理 器 (Pre-processor) :“ 编 译 上 下 文 " 指 的 是 某 个 “程序 ”里 涉及 到 的 
所 有 文件 。 上 下 文 的 创建 是 通过 检查 所 有 从 命令 行 上 传 入 编译 器 的 文件 ， 
按 顺 序 ， 然 后 再 加 入 这 些 文件 直接 引用 的 其 它 文 件 或 通过 import 语句 
和 /// «reference path=... /> 标签 间接 引用 的 其 它 文件 。 


沿 着 引用 图 走 下 来 你 会 发 现 它 是 一 个 有 序 的 源 文 件 列表 ， 它 们 组 成 了 整个 程序 。 S 
解析 导出 (import) ee 会 优先 选择 ".ts" 文 件 而 不 是 “.d.ts" 文 件 ， 以 确保 处 理 的 
是 最 新 的 文件 。 编译 器 会 进 行 与 Nodejs 相 似 的 流程 来 解析 导入 ， 沿 着 目录 链 查 找 与 
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将 要 导入 相 匹配 的 带 .ts 或 .dts 扩 展 名 的 文件 。 导入 失败 不 会 报 error， 因 为 可 能 已 经 
声明 了 外 部 模块 。 


e 独立 编译 器 (tsc) : 批 处 理 编 译 命令 行 界面 。 主 要 处 理 针对 不 同 支持 的 引擎 
读 写 文件 (比如 : Node.js) ° 


e 语言 服务 :“ 语 言 服务 "在 核心 编译 器 管道 上 暴露 了 额外 的 一 层 ， 非 常 适合 类 编 
辑 器 的 应 用 。 


语言 服务 支持 一 系列 典型 的 编辑 器 操作 比如 语 名 自动 补 全 ， 子 数 签名 提示 ， 代 码 格 
式 化 和 突出 高 亮 ， 着 色 等 。 基本 的 重 构 功能 比如 重 命名 ， 调 试 接口 辅助 功能 比如 验 
证 断 点 ， 还 有 TypeScript 特 有 的 功能 比如 支持 增 量 编译 (在 命令 行 上 使 用 -- 
watch ) 。 语 言 服务 是 被 设计 用 来 有 效 的 处 理 在 一 个 长 期 存在 的 编译 上 下 文中 文 
件 随 着 时 间 改 变 的 情况 ; 在 这 样 的 情况 下 ， 语 言 服务 提供 了 与 其 它 编译 器 接口 不 同 
的 角度 来 处 理 程序 和 源 文 件 。 


请 参考 [[Using the Language Service API]] 以 了 解 更 多 详细 内 容 。 


数据 结构 


e Node: 抽象 语法 树 (AST) 的 基本 组 成 块 。 通 常 Node 表示 语言 语法 里 的 非 终 
结 符 ; 一 些 终结 符 保 存在 语法 树 里 比如 标识 符 和 字面 量 。 


e SourceFile: 给 定 源 文件 的 AST。 SourceFile 本 身 是 一 个 Node ; 它 提 供 了 
额外 的 接口 用 来 访问 文件 的 源码 ， 文 件 里 的 引用 ， 文 件 里 的 标识 符 列表 和 文件 
里 的 某 个 位 置 与 它 对 应 的 行 号 与 列 号 的 映射 。 

e Program: SourceFile 的 集合 和 一 系列 编译 选项 代表 一 个 编译 单 


元 。 Program 是 类 型 系统 和 生成 代码 的 主 入 口 。 


e Symbol: 具名 的 声明 。 Symbols 是 做 为 联合 的 结果 而 创建 。 Symbols 连接 
了 树 里 的 声明 节点 和 其 它 对 同一 个 实体 的 声明 。 Symbols 是 语义 系统 的 基本 
构建 块 。 


e Type: Type 是 语义 系统 的 其 它 部 分 。 Type 可 能 被 命名 〈 比 如 ， 类 和 接 
B) ， 或 匿名 (tito > RRA) 。 


Signature: 一 共有 三 种 signature 类 型 : 调用 签名 (call) ， 构 造 签名 
(construct) 和 索引 签名 (index) 。 


编译 过 程 概述 


整个 过 程 从 预 处 理 开 始 。 预 处 理 器 会 萌出 哪些 文件 参与 编译 ， 它 会 去 查找 如 下 引用 


( /// «reference path=... /> 标签 和 import #4) ° 


语法 分 析 器 (Parser) 生成 抽象 语法 树 (AST) Node .这 些 仅 为 用 户 输 出 的 抽象 
表现 ， 以 树 的 形式 。 一 个 SourceFile 对 象 表 示 一 个 给 定 文件 的 AST 并 且 带 有 一 
些 额 外 的 信息 如 文件 名 及 源 文件 内 容 。 


然后 ， 联 合 器 (Binder) 处 理 AST 节 点 ， 结 合并 生成 Symbols 。 一 个 Symbol 会 
对 应 到 一 个 命名 实体 。 这 里 有 个 一 微妙 的 差别 ， 几 个 声明 节点 可 能 会 是 名 字 相 同 的 
实体 。 也 就 是 说 ， 有 时 候 不 同 的 Node 具有 相同 的 Symbol ， 并 且 每 

个 Symbol 保持 跟踪 它 的 声明 节点 。 比如 ， 一 个 名 字 相 同 

的 class 和 namespace 可 以 合并 ， 并 且 拥 有 相同 的 Symbol 。 联合 器 也 会 处 理 
作用 域 ， 以 确保 每 个 Symbol 都 在 正确 的 封闭 作用 域 里 创建 。 


生成 SourceFile (还 带 有 它 的 Symbols 们 ) 是 通过 调用 createSourceFile 
API ° 


到 目前 为 止 ， Symbol 代表 的 命名 实体 可 以 在 单个 文件 里 看 到 ， 但 是 有 些 声 明 可 以 
从 多 文件 合并 ， 因 此 下 一 步 就 是 构建 一 个 全 局 的 包含 所 有 文件 的 视图 ， 也 就 是 创建 
一 个 Program ° 


日 


一 个 Program 是 SourceFile 的 集合 并 带 有 一 系列 CompilerOptions 。 通过 
调用 createProgram APl 来 创建 Program ° 


通过 一 个 Program 实例 创建 TypeChecker 。 TypeChecker 是 TypeScript 类 型 
系统 的 核心 。 它 负责 计算 出 不 同文 件 里 的 symbols 之 间 的 关系 ， 将 Type 赋值 
给 Symbol ， 并 生成 任何 语义 Diagnostic (t+: error) ° 


TypeChecker 首先 要 做 的 是 合并 不 同 的 SourceFile 里 的 Symbol 到 一 个 单独 
的 视图 ， 创 建 单一 的 Symbol 表 ， 合 并 所 有 普通 的 Symbol (上 比如: 不 同文 件 里 


的 namespace ) 。 
在 原始 状态 初始 化 完成 后 ， Typechecker 就 可 以 解决 关于 这 个 程序 的 任何 问题 
To 这 些 "问题 "可 以 是 : 

e 这 个 Node 的 Symbol 是 什么 ? 


e 这 个 Symbol 的 Type 是 什么 ? 
e 在 AST 的 某 个 部 分 里 有 哪些 Symbol 是 可 见 的 ? 


e 某 个 函数 声明 的 signature 都 有 哪些 ? 
e 针对 某 个 文件 应 该 报 哪些 错误 ? 


TypeChecker 计算 所 有 东西 都 是 “懒惰 的 " ; 为 了 回答 一 个 问题 它 仅 “ 解 决 "必要 的 信 
息 。 Typechecker 仅 会 检测 和 这 个 问题 有 关 的 Node ， Symbol 或 Type ， 不 
会 检测 额外 的 实体 。 


对 于 一 个 Program 同样 会 生成 一 个 Emitter ° Emitter 负责 生成 给 
定 SourceFile 的 输出 ; 它 包括 : .js ^ .jsx * .d.ts fe .js.map ° 


Ad 


完整 开始 / 令 牌 开始 (Full Start/Token Start) 


J 


e 


令 牌 本 身 就 有 具有 我 们 称 为 一 个 “完整 开始 "和 一 个 “ 令 牌 开始 "。" 令 牌 开始 " 是 指 更 自然 
的 版 本 ， 它 表示 在 文件 中 令 牌 开始 的 位 置 。“ 完 整 开 始 " 是 指 从 上 一 个 有 意义 的 令 牌 
之 后 扫描 器 开始 扫描 的 起 始 位 置 。 当 关心 琐事 时 ， 我 们 往往 更 关心 完整 开始 。 


函数 描述 
ts.Node.getStart 取得 某 节点 的 第 一 个 令 牌 起 始 位 置 。 
ts.Node.getFullstart 取得 某 节 点 拥有 的 第 一 个 令 牌 的 完整 开始 。 


HEA (Trivia) 


语法 的 琐碎 内 容 代 表 源 码 里 那些 对 理解 代码 无 关 紧 要 的 内 容 ， 比 如 空白 ， 注 释 甚 至 
一 些 冲 突 的 标记 。 


因为 琐碎 内 容 不 是 语言 正常 语法 的 一 部 分 (不 包括 ECMAScript API 规 范 ) 并 且 可 能 
在 任意 2 个 令 牌 中 的 任意 位 置 出 现 ， 它 们 不 会 包含 在 语法 树 里 。 但 是 ， 因 为 它们 对 
FRE PAP ARAB GREE > PEL Seg AR EARS RA MAP Is 

Je] o 


因为 EndofFileToken 后 面 可 以 没有 任何 内 容 〈 令 牌 和 琐碎 内 容 ) o PUR BUT 
容 自然 地 在 非 琐碎 内 容 之 前 ， 而 且 存在 于 那个 令 牌 的 “完整 开始 "和 " 令 牌 开始 "之 间 。 


虽然 这 个 一 个 方便 的 标记 法 来 说 明 一 个 注释 “属于 ”一 个 Node 。 比 如 ， 在 下 面 的 例 
子 里 ， 可 以 明显 看 出 genie 函数 拥有 两 个 注释 : 


Wal X= 107077 This LS x. 


jee 
* Postcondition: Grants all three wishes. 
ey 
function genie([wishi, wish2, wish3]: [Wish, Wish, Wish]) { 
while (true) { 


j 
+ /7 End funetion 


RERESKE> RAFNAR var x = 10; Go 


我 们 依据 Roslyn's notion of trivia ownership 处 理 注释 所 有 权 。 通 常 来 讲 ， 一 个 令 牌 
拥有 同一 行 上 的 所 有 的 琐碎 内 容 直 到 下 一 个 令 牌 开始 。 任 何 出 现在 这 行 之 后 的 注释 
都 属于 下 一 个 令 牌 。 源 文件 的 第 一 个 令 牌 拥有 所 有 的 初始 琐 态 内容， 并且 最 后 面 的 
一 系列 琐碎 内 容 会 添加 到 end-of-file 令 牌 上 。 


对 于 大 多 数 普 通用 户 ， 注 释 是 "有趣 的 "琐碎 内 容 。 属 于 一 个 节点 的 注释 内 容 可 以 通 
过 下 面 的 函数 来 获取 : 


函数 描述 


提供 源 文件 和 一 个 指定 位 置 ， 返 回 指定 
位 置 后 的 第 一 个 换行 与 令 牌 之 间 的 注释 
的 范围 (与 ts.Node.getFullstart 配 
合 会 更 有 用 ) 。 


提供 源 文件 和 一 个 指定 位 置 ， 返 回 到 指 
定位 置 后 第 一 个 换行 为 止 的 注释 的 范围 
(与 ts.Node.getEnd 配合 会 更 有 
A) œ 


ts.getLeadingCommentRanges 


ts.getTrailingCommentRanges 


做 为 例子 ， 假 设 有 下 面 一 部 分 源 代 码 : 


debugger /*hello*/ 
//bye 
ZERO function 


function 关键 字 的 完整 开始 是 从 /*hello*/ 注释 ， 但 
是 getLeadingCommentRanges 仅 会 返回 后 面 2 个 注释 : 


dee batkid Wise vrac te eo/ [CR] [NL] _ _ 


PoP payne GRA Nn te ele Deuil 
1 1 
1 1 1 
完整 开始 查找 
第 一 个 注释 第 二 个 注释 令 牌 开始 
开始 注释 


适当 地 ， 在 debugger 语句 后 调用 getTrailingCommentRanges 可 以 提取 
出 /*hello*/ 注释 。 


如 果 你 关心 令 牌 流 的 更 多 信息 ， createScanner 也 有 一 个 skipTrivia 标记 ， 你 
可 以 设置 成 false ， 然 后 使 用 setText / setTextPos 来 扫描 文件 里 的 不 同位 
署 。 

EL 
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2.1 


调查 Function bind 操作 符 
支持 工程 引用 

readonly 修饰 符 
调查 具名 类 型 支持 


Language Service API 里 支持 代码 重 构 功能 


扁平 化 声明 


2.0 


切换 到 基于 转换 的 生成 器 

支持 ES5/ES3 async / await 

支持 ES7 对 象 属性 展开 及 剩余 属性 

规定 函数 的 this 类 型 

属性 访问 上 的 类 型 保护 

切换 类 型 保护 

支持 常量 和 Symbol 上 计算 属性 的 类 型 检查 
可 变 类 型 


函数 表达 式 及 箭头 函数 的 装饰 器 
支持 节点 注册 句子 

在 tsconfig.json 里 支持 Glob 

在 语言 服务 API 里 支持 快速 修复 
在 tsserver/ 语 言 服务 APl 里 集成 tsd 
从 js 文件 的 JSDoc 里 撮 类 型 信息 
增强 lib.d.ts 模 块 化 

支持 外 部 辅助 代码 库 

调查 语言 服务 的 可 扩展 性 


1.8 
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发 展 路 线 图 


e 在 TypeScript 编 译 时 使 用 --allowjs 允许 JavaScript 

e 在 循环 里 允许 捕获 的 let / const 

e 标记 死 代 码 

e 使 用 --outFile 连接 模块 输出 

e tsconfig.json 里 支持 注释 

e 使 用 --pretty 为 终端 里 的 错误 信息 添加 样式 

e 支持 --outFile 给 命名 的 管道 套 接 字 和 特殊 设备 

e 支持 使 用 名 字 字 面 量 的 计算 属性 

e 字符 串 字面 量 类 型 

e JSX 无 状态 的 功能 性 组 件 

e 优化 联合 / 交 类 型 接口 

e 支持 F-Bounded 多 态 性 

e 支持 全 路 径 -project / -p 参数 

e 在 SystemJS 使 用 --allowSyntheticDefaultImports 支持 default 导入 操 
作 

e 识别 JavaScript 里 原型 的 赋值 

e 在 模块 里 使 用 路 径 映 身 

e 在 其 它 模 块 里 增加 global/module 作 用 域 

e 在 Visual Studio 使 用 tsconfig.json 做 为 高 优先 级 的 配置 

e 基于 this 类 型 保护 

e 支持 自 定义 JSX 工 厂 通过 --reactNamespace 

e 增强 for-in 语 名 检查 

e JSX 代 码 在 VS 2015 €. S ž 

e 发 布 TypeScript NuGet 包 


e 多 态 的 this 类 型 

e 支持 --module 的 --target es6 

e 支持 目标 为 ES3 时 使 用 装饰 器 

e 为 ES6 支 持 async / await (Node v4) 
e 增强 的 字面 量 初始 化 器 解构 检查 
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发 展 路 线 图 


1.6 


e ES6 Generators 

e Local types 

e 泛 型 别名 

e 类 继承 语句 里 使 用 表达 式 
e Class 表 达 式 

e tsconfig.json 的 exclude 属性 
e 用 户 定义 的 类 型 保护 函数 
o 增强 外 部 模块 解析 

e JSX 支 持 

e abstract 类 和 方法 

e 严格 的 对 但 字面 量 赋值 检查 
e 类 和 接口 的 声明 合并 

e 新 增 --init 


1.5 


e 支持 解构 

e 支持 展开 操作 符 

e 支持 ES6 模 块 

e 支持 for .of 

e 支持 ES6 Unicode 规范 

e 支持 Symbols 

e 支持 计算 属性 

e 支持 tsconfig.json 文 件 

e 支持 ES3/ES5 的 let 和 const 

e 支持 ES3/ES5 带 标记 的 模版 

e 暴露 一 个 新 的 编辑 器 接口 通过 TS Server 
e 支持 ES7 装饰 器 提案 
e 支持 装饰 器 类 型 元 信 ， 
e 新 增 --rootDir 

e 新 增 ts.transpile API 
e 支持 --module umd 
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e 支持 --module system 

e 新 增 --noEmitHelpers 

e 新 增 --inlineSourceMap 

e 新 增 --inlineSources 

e 新 增 --newLine 

e 新 增 --isolatedModules 

e 支持 新 的 namespace 关键 字 

e 支持 Visual Studio 2015 的 tsconfig.json 

e 增强 Visual Studio 2013 的 模块 字面 量 高 亮 


1.4 


e 支持 联合 类 型 和 类 型 保护 
e 新 增 --noEmitOnError 

e 新 增 --target ES6 

e 支持 Let and Const 

e 支持 模块 字面 量 

e Library typings for ES6 
e 支持 Const enums 

e 导出 语言 服务 公共 API 


1.3 


e 为 新 的 编译 器 重 写 语言 服务 
e 支持 受 保 护 的 成 员 in classes 
e 支持 元 组 类 型 


430 


se. hÓ +h AL 
新 增 功 能 


TypeScript 新 增 内 容 


e TypeScript 2.4 
e TypeScript 2.3 
e TypeScript 2.2 
e TypeScript 2.1 
e TypeScript 2.0 
e TypeScript 1.8 
e TypeScript 1.7 
e TypeScript 1.6 
e TypeScript 1.5 
e TypeScript 1.4 
e TypeScript 1.3 
e TypeScript 1.1 


TypeScript 2.7 


更 严格 的 类 属性 检查 


TypeScript 2.7 引 入 了 一 个 新 的 控制 严格 性 的 标记 -- 


strictPropertyInitialization ! 


4 FR ARICA RK 05] AES Sc 1] By EARS He 1 3S ACE SUR T] BE 46 16 BA 
值 。 在 某 种 意义 上 ， 它 会 明确 地 进行 从 变量 到 类 的 实例 属性 的 赋值 检查 。 比 如 : 


class C { 
foo: number; 
bar = "hello": 
baz: boolean; 
"M 
// Error! Property 'baz' has no initializer and is not assigned 
directly in the constructor. 
constructor() { 
this.foo - 42; 


上 例 中 ， baz 从 未 被 赋值 ， 因 此 TypeScript 报 错 了 。 如 果 我 们 的 本 意 就 是 
让 baz 可 以 为 undefined ， 那 么 应 该 声明 它 的 类 型 为 boolean | 


undefined ° 


在 某 些 场景 下 ， 属 性 会 被 间接 地 初始 化 (使 用 辅助 方法 或 依赖 注入 库 ) 9 这 种 情况 
下 ， 你 可 以 在 属性 上 使 用 显 式 赋值 断言 来 帮助 类 型 系统 识别 类 型 。 


class C { 
foo!: number; 
MY A 
// Notice this exclamation point! 
// This is the "definite assignment assertion" modifier. 
constructor() { 
this.initialize(); 


initialize() { 
this.foo = 0; 


注意 ， --strictPropertyInitialization 会 连同 其 它 --strict 模式 标记 一 起 
被 局 用， 这 可 能 会 影响 你 的 工程 。 你 可 以 

在 tsconfig.json 的 compilerOptions € 

将 strictPropertyInitialization 设置 为 false ， 或 者 在 命令 行 上 将 -- 
strictPropertyInitialization 设置 为 false 来 关闭 检查 。 


显 式 赋值 断言 


尽管 我 们 尝试 将 类 型 系统 做 的 更 富 表现 力 ， 但 我 们 知道 有 时 用 户 比 TypeScript 更 加 
了 解 类 型 。 


上 面 提 到 过 ， 显 式 赋值 断言 是 一 个 新 语法 ， 使 用 它 来 告诉 TypeScript 一 个 属性 会 被 
明确 地 赋值 。 但 是 除了 在 类 属性 上 使 用 它 之 外 ， 在 TypeScript 2.7 里 你 还 可 以 在 变 
X P ER! 


let x!: number[]; 
initialize(); 
x.push(4); 


function initialize() ( 
X = [0, dis 2" 917 


假设 我 们 没有 在 x 后 面 加 上 感叹 号 ， 那 么 TypeScript 会 报告 x 从 未 被 初始 化 过 。 
它 在 延迟 初始 化 或 重新 初始 化 的 场景 下 很 方便 使 用 。 


更 便利 的 与 ECMAScript 模 块 的 互通 性 


ECMAScript 模 块 在 ES2015 里 才 被 标准 化 ， 在 这 之 前 ，JavaScript 生 态 系统 里 存在 
几 种 不 同 的 模块 格式 ， 它 们 工作 方式 各 有 不 同 。 当 新 的 标准 通过 后 ， 社 区 遇 到 了 
一 个 难题 ， 就 是 如 何在 已 有 的 “老式 "模块 模式 之 间 保 证 最 佳 的 互通 性 。 


TypeScript 与 Babel 采 取 了 不 同 的 方案 ， 并 且 直 到 现在 ， 还 没 出 现 丨 正 地 固定 标准 。 
简单 地 说 ， 如 果 你 使 用 Babel，Webpack 或 React Native > #312 5j te VA 4E 1% M «s 
不 同 的 导入 行为 ， 我 们 提供 了 一 个 新 的 编译 选项 --esModuleInterop 。 


TypeScript 与 Babel 都 允许 用 户 导 入 CommonJS 模 块 做 为 默认 导入 ， 但 是 仍然 在 导 
入 的 命名 空间 上 提 供 了 每 个 属性 (除非 模块 使 用 了 — esModule 标记 ) 。 


import _, { pick } from "lodash"; 


—psck0o je 
pick(...); 


由 于 TypeScript 的 不 同行 为 ， 我 们 在 TypeScript 1.8 里 增加 了 -- 
allowSyntheticDefaultImports 标记 ， 人 允许 用 户 在 这 种 行为 下 检查 类 型 (并非 
输出 ) 。 


通常 ， 在 TypeScript 视 角 下 的 CommonJS (和 AMD) 模块 ， 命 名 空间 导入 总 是 相当 
于 CommonJS 模 块 对 象 的 结构 ， 一 个 默认 导入 仅 相 当 于 模块 上 一 个 名 字 叫 
做 default 的 成 员 。 在 这 种 假定 下 ， 你 可 以 创建 一 个 命名 导入 

import { range } from "lodash"; 


for (let i of range(10)) { 


j 


然而 ，ES 命 名 空间 导入 不 能 被 调用 ， 因 此 这 种 方案 并 非 总 是 可 行 。 


import * as express from "express"; 


// Should be an error in any valid implementation. 


let app = express(); 
为 了 允许 用 户 使 用 与 Babel 或 Webpack 一 致 的 运行 时 行为 ，TypeScript 提 供 了 一 个 
新 的 --esModuleInterop 标记 ， 它 用 于 输出 晶 模 块 格 式 。 
当 使 用 这 个 新 的 --esModuleInterop 标记 时 ， 可 调用 的 CommonJS 模 块 必须 被 做 
为 默认 导入 : 

import express from "express"; 


let app = express(); 
我 们 强烈 建议 Node.js 用 户 利用 这 个 标记 ， 当 一 个 库 的 模块 输出 目标 为 commonjs 
时 ， 例 如 express， 它 会 导入 一 个 可 调用 /可 构造 的 模块 。 


Webpack 用 户 也 可 以 使 用 它 ; 然而 ， 你 们 代码 应 该 将 目标 设置 
为 esnext 且 moduleResolution 策略 为 node 。 使 用 esnext 模块 和 -- 
esModuleInterop 等 同 于 启用 了 --allowSyntheticDefaultImports 。 


unique symbol 类 型 和 常量 名 属性 


TypeScript 2.7 对 ECMAScript 里 的 symbols 有 了 更 深入 的 了 解 ， 你 可 以 更 灵活 地 
使 用 它们 。 


一 个 需求 很 大 的 用 例 是 使 用 symbols 来 声明 一 个 类 型 良好 的 属性 。 比 如， 看 下 面 
的 例子 : 


const Foo = Symbol("Foo"); 
const Bar = Symbol("Bar"); 


let x = { 
[Foo]: 100, 
[Bar]: "hello", 
3 
let a - x[Foo]; // has type 'number' 
let b - x[Bar]; // has type 'string' 


你 可 以 看 到 ，TypeScript 可 以 追踪 到 x 拥有 使 用 符号 Foo fe Bar 声明 的 属性 ， 
因为 Foo 和 Bar 被 声明 成 常量 。 TypeScript 利 用 了 这 一 点 ， 让 Foo 和 Bar 有 具 
有 了 一 种 新 类 型 : unique symbols 。 


unique symbols Æ symbols 的 子 类 型 ， 仅 可 通过 调 

用 Symbol() 或 Symbol.for() 或 由 明确 的 类 型 注释 生成 。 它们 仅 出 现在 常量 声 
明和 只 读 的 静态 属性 上 ， 并 且 为 了 引用 一 个 存在 的 unique symbols 类 型 ， 你 必 
HAS typeof 操作 符 。 每 个 对 unique symbols 的 引用 都 意味 着 一 个 完全 唯一 
的 声明 身份 。 


// Works 
declare const Foo: unique symbol; 


// Error! 'Bar' isn't a constant. 
let Bar: unique symbol = Symbol(); 


// Works - refers to a unique symbol, but its identity is tied t 
Ge Ons 
let Baz: typeof Foo = Foo; 


// Also works. 
class C { 
static readonly StaticSymbol: unique symbol = Symbol(); 


因为 每 个 unique symbols 都 有 个 完全 独立 的 身份 ， 因 此 两 个 unique 
symbols 类 型 之 前 不 能 赋值 和 比较 。 


const Foo Symbol(); 


Symbol(); 


const Bar 


// Error: can't compare two unique symbols. 
if (Foo === Bar) { 
OA 


另 一 个 可 能 的 用 例 是 使 用 symbols 做 为 联合 标记 。 


// ./ShapeKind.ts 
export const Circle = Symbol("circle"); 
export const Square = Symbol("square"); 


// ./ShapeFun.ts 
import * as ShapeKind from "./ShapeKind"; 


interface Circle ( 
kind: typeof ShapeKind.Circle; 
radius: number; 


interface Square { 
kind: typeof ShapeKind.Square; 
sideLength: number; 


function area(shape: Circle | Square) { 
if (shape.kind --- ShapeKind.Circle) ( 
// 'shape' has type 'Circle' 
return Math.PI * shape.radius ** 2; 
} 
// 'shape' has type 'Square' 
return shape.sideLength ** 2; 


--watch 模式 下 具有 更 简洁 的 输出 


在 TypeScript 的 --watch 模式 下 进行 重新 编译 后 会 清 屏 。 这 样 就 更 方便 阅读 最 近 
这 次 编译 的 输出 信息 。 


更 漂亮 的 --pretty 输出 


TypeScript 的 --pretty 标记 可 以 让 错误 信息 更 易 阅 读 和 管理 。 我 们 对 这 个 功能 进 
行 了 两 个 主要 的 改进 。 HL: --pretty 对 文件 名 ， 诊 段 代 码 和 行 数 添加 了 颜色 

(感谢 Joshua Goldberg) » 其 次 ， 格 式 化 了 文件 名 和 位 置 ， 以 变 于 在 常用 的 终端 
里 使 用 Ctrl+Click，Cmd+Click，Alt+Click 等 来 跳 转 到 编译 器 里 的 相应 位 置 。 


数字 分 隔 符 


TypeScript 2.7 支 持 ECMAScript 的 数字 分 隔 符 提案 。 这 个 特性 允许 用 户 在 数字 之 间 
使 用 下 划 线 (C) 来 对 数字 分 组 (就 像 使 用 过 号 和 点 来 对 数字 分 组 那样 ) 。 

// Constants 

const COULOMB = 8.957_551_787e9; // N-m^2 / C^2 

const PLANCK = 6.626 070 040e-34; // J-s 

const JENNY = 867 5309; // C-A-L^2 


这 些 分 隔 符 对 于 二 进 制 和 十 六 进 制 同样 有 用 。 


let bits = 0b0010_1010; 
let routine = OxCOFFEE FOOD BED; 
let martin - OxFO 1E 


注意 ， 可 能 有 些 反 常识 ，JavaScript 里 的 数字 表示 信用 卡 和 电话 号 并 不 适当 。 这 种 
情况 下 使 用 字符 串 更 好 。 


固定 长 度 元 组 


TypeScript 2.6 之 前 ， [number，string，string] 被 当 作 [number, 
string] 的 子 类 型 。 这 是 由 于 TypeScript 的 结构 性 类 型 系统 而 造成 的 ; [number， 
string，string] 的 第 一 个 和 第 二 个 元 素 是 [number，string] 里 相应 的 第 一 个 


和 第 二 个 元 素 的 子 类 型 ， 并 且 "“ 末 尾 的 "字符 串 类 型 是 可 以 赋值 给 [number， 
string] 里 元 素 的 联合 类 型 的 。 然 而 ， 在 查看 了 现实 中 元 组 的 丨 实用 法 后 ， 我 们 
注意 到 大 多 数 情 况 下 这 是 不 被 允许 的 。 


感谢 Tycho Grouwstra 提 交 的 PR， 元 组 类 型 会 考虑 它 的 长 度 ， 不 同 长 度 的 元 组 不 再 
允许 相互 赋值 。 它 通过 数字 字面 量 类 型 实现 ， 因 此 现在 可 以 区 分 出 不 同 长 度 的 元 组 
Ta 


概念 上 讲 ， 你 可 以 把 [number，string] 类 型 等 同 于 下 面 的 NumStrTuple * 
明 : 


interface NumStrTuple extends Array<number | string> { 
0: number; 
A String; 
length: 2; // using the numeric literal type '2' 


请 注意 ， 这 是 一 个 破坏 性 改动 。 如 果 你 想 要 以 前 的 行为 ， 让 元 组 仅 限制 最 小 的 长 
那么 你 可 以 使 用 一 个 类 似 的 声明 但 不 明确 地 指定 长 度 属性 ， 回 退 到 数字 。 


interface MinimumNumStrTuple extends Array<number | string> { 
0: number; 
SG 


in 操作 符 细 化 和 精确 的 instanceof 


TypeScript 2.7 带 来 了 两 处 类 型 细 化 方面 的 改动 - 通过 执行 “类 型 保护 "确定 更 详细 类 
型 的 能 力 。 


Tc T La RAR SAT 2 告 构 兼 容 性 ， 能 更 准确 地 
反映 出 instanceof 操作 符 在 运行 时 的 行为 。 这 可 以 帮助 避免 一 些 复 杂 的 问题 ， 
44% Fl instanceof 去 细 化 结构 上 相似 (但 无 关 ) 的 类 型 时 。 


其 次 ， 感 谢 GitHub 用 户 ldeaHunter， in 操作 符 现在 做 为 类 型 保护 使 用 ， 会 细 化 掉 
没有 明确 声明 的 属性 名 。 


interface A { a: number }; 
interface B { b: string }; 


function foo(x: A | B) { 
af “Ca an X) i 
return X.a; 


} 


return x.b; 


LF AEH ALTE SET 
在 JavaScript 里 有 一 种 模式 ， 用 户 会 忽略 掉 一 些 属性 ， 稍 后 在 使 用 的 时 候 那 些 属性 


的 值 为 undefined ° 


let foo = someTest ? { value: 42 } : {}; 


在 以 前 TypeScript 会 查找 ( value: number } 和 {} 的 最 佳 超 类 型 ， 结 果 

是 {} o 这 从 技术 角度 上 讲 是 正确 的 ， 但 并 不 是 很 有 用 。 

从 2.7 版 本 开始 ，TypeScript 会 “规范 化 "每 个 对 象 字 面 量 类 型 记录 每 个 属性 ， 为 每 
个 undefined 类 型 属性 插入 一 个 可 选 属性 ， 并 将 它们 联合 起 来 。 

在 上 例 中 ， foo 的 最 类 型 是 { value: number } | { value?: undefined 

} 。 结合 了 TypeScript 的 细 化 类 型 ， 这 让 我 们 可 以 编写 更 具 表 达 性 的 代码 且 
TypeScript 也 可 理解 。 看 另外 一 个 例子 : 


TypeScript 2.7 


// Has type 
// | { a: boolean, aData: number, b?: undefined } 
// | { b: boolean, bData: string, a?: undefined } 
let bar = Math.random() < 0.5 ? 

{ a: true, aData: 100 } : 

{ b: true, bData: "hello" }; 


if (bar.b) { 
// TypeScript now knows that 'bar' has the type 
VA 
2 '( b: boolean, bData: string, a?: undefined y! 
Und 


// so it knows that 'bData' is available. 
bar.bData.toLowerCase( ) 


这 里 ，TypeScript 可 以 通过 检查 b 属性 来 细 化 bar 的 类 型 ， 然 后 允许 我 们 访 
问 bData 属性 。 


441 


TypeScript 2.6 


严格 函数 类 型 


TypeScript 2.6 引 入 了 新 的 类 型 检查 选项 ， --strictFunctionTypes 。 -- 
strictFunctionTypes 选项 是 --strict 系列 选项 之 一 ， 也 就 是 说 -- 
strict 模式 下 它 默认 是 启用 的 。 你 可 以 通过 在 命令 行 或 tsconfig.json 中 设置 -- 
strictFunctionTypes false 来 单独 禁用 它 。 


--strictFunctionTypes 启用 时 ， 郊 数 类 型 参数 的 检查 是 抗 变 
(contravariantly) 而 非 双 变 (bivariantly) 的 。 关 于 变 体 (variance) 对 于 有 函数 类 型 
意义 的 相关 背景 ， 请 查看 协 变 (covariance) 和 抗 变 (contravariance) 是 什么 ?。 


这 一 更 严格 的 检查 应 用 于 除 方法 或 构造 函数 声明 以 外 的 所 有 元 数 类 型 。 方 法 被 专门 
排除 在 外 是 为 了 确保 带 泛 型 的 类 和 接口 (如 Array) 总 体 上 仍然 保持 协 变 。 


考虑 下 面 这 个 Animal 是 Dog 和 Cat 的 父 类 型 的 例子 : 


declare let f1: (x: Animal) => void; 

declare let f2: (x: Dog) => void; 

declare let f3: (x: Cat) => void; 

f1 = f2; // 局 用 --strictFunctionTypes 时 错误 
p2n-spl m eas 
f2 = f3; // 错误 





第 一 个 赋值 语句 在 默认 的 类 型 检查 模式 中 是 多 许 的， 但 是 在 严格 函数 类 型 模式 下 会 
被 标记 错误 。 通 俗 地 讲 ， 默 认 模 式 允 许 这 么 赋值 ， 因 为 它 可 能 是 合理 的 ， 而 严格 函 
数 类 型 模式 将 它 标记 为 错误 ， 因 为 它 不 能 被 证 明 合理 。 任 何 一 种 模式 中 ， 第 三 个 赋 
值 都 是 错误 的 ， 因 为 它 永远 不 合理 。 


用 另 一 种 方式 来 描述 这 个 例子 则 是 ， 默 认 类 型 检查 模式 中 T 在 类 型 (x: T) => 
void 是 双 变 的 (也 即 协 变 或 抗 变 ) ， 但 在 严格 函数 类 型 模式 中 T 是 抗 变 的 。 


例子 


interface Comparer<T> { 
compare: (a: T, b: T) => number; 


declare let animalComparer: Comparer<Animal>; 
declare let dogComparer: Comparer<Dog>; 


animalComparer = dogComparer;  // 和 错误 





dogComparer - animalComparer;  // 


现在 第 一 个 赋值 是 错误 的 。 更 明确 地 说 ， Comparer<T> 中 的 T 因为 仅 在 函数 类 
型 参数 的 位 置 被 使 用 ， 是 抗 变 的 。 


另外 ， 注 意 尽管 有 的 语言 (比如 C# 和 Scala) 要 求 变 体 标 注 〈variance 
annotations) ( out / in 或 +/- )， 而 由 于 TypeScript 的 结构 化 类 型 系统 
它 的 变 体 是 由 泛 型 中 的 类 型 参数 的 实际 使 用 自然 得 出 的 。 


启用 --strictFunctionTypes 时 ， 如 果 compare 被 声明 为 方法 ， 则 第 一 个 赋值 
依然 是 被 允许 的 。 更 明确 的 说 ， Comparer<T> 中 的 T 因为 仅 在 方法 参数 的 位 置 
被 使 用 所 以 是 双 变 的 。 


interface Comparer<T> { 
compare(a: T, b: T): number; 
declare let animalComparer: Comparer<Animal>; 


declare let dogComparer: Comparer<Dog>; 


animalComparer = dogComparer; // 正确 ， 因 为 双 变 





dogComparer = animalComparer; // 


TypeScript 2.6 还 改进 了 与 抗 变 位 置 相关 的 类 型 推导 : 


function combine<T>(...funcs: ((x: ) => void)[]): (x: T) => void 
{ 
return x => { 
for (const f of funcs) f(x); 


function animalFunc(x: Animal) {} 
function dogFunc(x: Dog) {} 


let combined = combine(animalFunc > dogFunc); // (x: Dog) => voi 
d 


o 
by 


这 上 面 所 有 T 的 推断 都 来 自 抗 变 的 位 置 ， 由 此 我 们 得 出 T 的 最 普遍 子 类 型 
与 从 协 变 位 置 推导 出 的 结果 恰恰 相反 ， 从 协 变 位 置 我 们 得 出 的 是 最 普遍 超 类 型 。 


缓存 模块 中 的 标签 模板 对 象 


TypeScript 2.6 修 复 了 标签 字符 串 模 板 的 输出 ， 以 更 好 地 遵循 ECMAScript 标 准 。 TR 
据 ECMAScript 标准 ， 每 一 次 获取 模板 标签 的 值 时 ， 应 该 将 同一 个 模板 字符 串 数 组 
对 象 (同一 个 TemplatestringArray ) 作为 第 一 个 参数 传递 。 在 TypeScript 2.6 
之 前 ， 每 一 次 生成 的 都 是 全 新 的 模板 对 象 。 虽然 字符 串 的 内 容 是 一 样 的 ， 这 样 的 输 
出 会 影响 通过 识别 字符 串 来 实现 缓存 失效 的 库 ， 比 如 lit-html ° 


例子 


export function id(x: TemplateStringsArray) { 
return x; 


export function templateObjectFactory() { 
return id hello world’; 


let result = templateObjectFactory() === templateObjectFactory( ) 
pf AS 2 oan enue 


编译 后 的 代码 : 


"use strict"; 
var __makeTemplateObject = (this && this.__makeTemplateObject) | 
| function (cooked, raw) ( 

if (Object.defineProperty) { Object.defineProperty(cooked, 
raw", { value: raw }); } else { cooked.raw = raw; } 

return cooked; 


ia 


function id(x) { 


return x; 
} 
var _a; 
function templateObjectFactory() { 
return id(_a || (_a = __makeTemplateObject(["hello world"], [ 
"hello world"]))); 
y 
var result - templateObjectFactory() --- templateObjectFactory() 


国 EE 


注意 : 这 一 改变 引入 了 新 的 工具 函数 ， _ makeTemplateObject ; 如 果 你 在 搭 
配 使 用 --importHelpers 和 tslib ， 需 要 更 新 到 1.8 或 更 高 版 本 。 


本 地 化 的 命令 行 诊断 消息 


TypeScript 2.6 npm 包 加 入 了 13 种 语言 的 诊断 消息 本 地 化 版 本 。 命令 行 中 本 地 化 消 
息 会 在 使 用 --locale 选项 时 显示 。 


例子 


俄语 显示 的 错误 消息 : 


c:\ts>tsc --v 
Version 2.6.1 


c:\ts>tsc --locale ru --pretty c:\test\a.ts 


../test/a.ts(1,5): error TS2322: Tun ""string"" He MoxeT 6bITP Ha 
3HaueH gna Tuna "number". 


1 var x: number = "String"; 


2h 


中 文 显 示 的 帮助 信息 : 


PS C:\ts> tsc --V 
Version 2.6.1 


PS C:\ts> tsc --locale zh-cn 
版 本 2.6.1 
qr tse Fal d 


示例 : tsc hello.ts 
tsc --outFile file.js file.ts 
tsc @args.txt 


选项 : 

-h, --help 打印 此 消息 。 

--all 显示 所 有 编译 器 选项 。 

-v, --version 打印 编译 器 的 版 本 。 

--init 初始 化 TypeScript 项 目 并 创建 tsconfi 
g.json 文件 。 

-p 文件 或 目录 ，--project 文件 或 目录 编译 给 定 了 其 配置 文件 路 径 或 带 "t 
sconfig.json" 的 文件 夹 路 径 的 项 目 。 

--pretty 使 用 颜色 和 上 下 文风 格 化 错误 和 消息 (实验 ) 

-w, --watch 监视 输入 文件 。 

-t 版 本 ，--target 版 本 指定 ECMAScript 目标 版 本 : "ES3"( 
Ri) > "ESS". "ES2015" ^ "ES2016" ` "ES2017" 或 "ESNEXT" ° 

-m 种 类 ，--module 种 类 指定 模块 代码 生成 : "none"、"commonj 


s"、"amd"、"system"、"umd"、"es2015" 或 "ESNext" » 


--lib 指定 要 在 编译 中 包括 的 库 文件 : 
'esb' 'es6' 'es2015' 'es7' 'es2 
016' 'es2017' 'esnext' 'dom' 'dom.iterable' 'webworker' 'scripth 
ost’ 'es2015.core' 'es2015.collection' 'es2015.generator' 'es201 
5.iterable' 'es2015.promise' 'es2015.proxy' 'es2015.reflect' ‘es 


2015.symbol' 
s2017.0bject' 
'esnext.asynciterable' 
--allowJs 
--jsx 种 类 
act-native" 或 "react"。 -d, 
ES 
--sourceMap 
--outFile 文件 
--outDir 目录 
--removeComments 
--noEmit 
--strict 
--noImplicitAny 
发 错误 。 
--strictNullChecks 
--strictFunctionTypes 
--noImplicitThis 
引发 错误 。 
--alwaysStrict 
"use strict" 指令 。 
- -noUnusedLocals 
--noUnusedParameters 
--noImplicitReturns 


错误 。 


--noFallthroughCasesInSwitch 
情况 的 错误 。 

--types 

@< xX t» 


E 


'es2015.symbol.wellknown' 
'es2017.sharedmemory' 


- -declaration 





'es2016.array.include' 'e 
'es2017.string' "es2017.1nt1) 
允许 编译 JavaScript 文件 。 
指定 JSX 代码 生成 : "preserve" ^ "re 
生成 相应 的 


生成 相应 的 ".map" 文件 。 
连接 输出 并 将 其 发 出 到 单个 文件 。 
将 输出 结构 重 定向 到 目录 。 
请 勿 将 注释 发 出 到 输出 。 
请 勿 发 出 输出 。 
启用 所 有 严格 类 型 检查 选项 。 
对 具有 隐 式 "any" 类 型 的 表达 式 和 声明 引 


启用 严格 的 NULL 检查 。 
对 函数 类 型 启用 严格 检查 。 
在 带 隐 式 "any" 类 型 的 "this" 表达 式 上 
以 严格 模式 进行 分 析 ， 并 为 每 个 源 文件 发 出 
报告 未 使 用 的 局 部 变量 上 的 错误 。 
报告 未 使 用 的 参数 上 的 错误 。 
在 隐 数 中 的 所 有 代码 路 径 并 非 都 返回 值 时 报告 


报告 switch 语句 中 遇 到 fallthrough 


要 包含 在 编译 中 类 型 声明 文件 。 
从 文件 插入 命令 行 选项 和 文件 。 


—— 4 


通过 "I| @ts-ignore’ 注释 隐藏 .ts 文件 中 的 错误 


TypeScript 2.6 支 持 在 .ts 文件 中 通过 在 报错 一 行 上 方 使 用 // Qts-ignore 来 忽略 


EAT TK ° 
例子 


if (false) { 
// @ts-ignore : 无 法 被 执行 的 代码 的 错误 


console. log("hello"); 


// Qts-ignore 注释 会 忽略 下 一 行 中 产生 的 所 有 错误 。 建议 实践 中 在 @ts- 
ignore 之 后 添加 相关 提示 ， 解 释 忽 略 了 什么 错误 。 


请 注意 ， 这 个 注释 仅 会 隐藏 报错 ， 并 且 我 们 建议 你 极 少 使 用 这 一 注释 。 


更 快 的 tse --watch 


TypeScript 2.6 带 来 了 更 快 的 --watch 实现 。 新 版 本 优化 了 使 用 ES 模块 的 代码 的 
生成 和 检查 。 在 一 个 模块 文件 中 检测 到 的 改变 只 会 使 改变 的 模块 ， 以 及 依赖 它 的 文 
件 被 重新 生成 ， 而 不 再 是 整个 项 目 。 有 大 量 文件 的 项 目 应 该 从 这 一 改变 中 获 益 最 


Bo 


这 一 新 的 实现 也 为 tsserver 中 的 监听 带 来 了 性 能 提升 。 监 听 逻 辑 被 完全 重 写 以 更 快 
响应 改变 事件 。 


只 写 的 引用 现在 会 被 标记 未 使 用 


TypeScript 2.6 加 入 了 修正 的 --noUnusedLocals 和 --noUnusedParameters 编 
译 选 项 实现 。 只 被 写 但 从 没有 被 读 的 声明 现在 会 被 标记 未 使 用 。 
例子 


下 面 n 和 m 都 会 被 标记 为 未 使 用 ， 因 为 它们 的 值 从 未 被 读 取 。 之 前 TypeScript 
只 会 检查 它们 的 值 是 否 被 引用 。 


TypeScript 2.6 


function f(n: number) ( 


n-90; 
} 
class € f 
private m: number; 
constructor() { 
this.m - 0; 
} 
} 


另外 仅 被 自己 内 部 调用 的 函数 也 会 被 认为 是 未 使 用 的 。 


例子 


function f() { 
f(); // 错误 : 'f' 被 声明 ， 但 它 的 值 从 未 被 使 用 


TypeScript 2.5 


可 选 的 catch 语句 变量 


得 益 于 @tinganho 所 做 的 工作 ，TypeScript 2.5 实 现 了 一 个 新 的 ECMAScript 特 性 ， 
允许 用 户 省 略 catch 语句 中 的 变量 。 例 如 ， 当 使 用 JsON.parse 时 ， 你 可 能 需 
要 将 对 应 的 函数 调用 放 在 try / catch 中 ， 但 是 最 后 可 能 并 不 会 用 到 输入 有 误 时 
会 抛 出 的 SyntaxError (语法 错误 ) ° 


let input ="... ."; 
try A 
JSON.parse(input); 
j 
catch { 
// NE REI catch Jp AA PARSE * 
console.log("4&A£&j JSON 不 合 sant + input) 
} 


checkJs / Qts-check 模式 中 的 类 型 断言 /转换 
语法 
TypeScript 2.5 引入 了 在 使 用 纯 JavaScript 的 项 目 中 断言 表达 式 类 型 的 能 力 。 对 应 
的 语法 是 /xx Qtype {...} */ 标注 注释 后 加 上 被 圆 括 号 括 起 来 ， 类 型 需要 被 重 
新 演算 的 表达 式 。 举 例 : 


var x = /** @type {SomeType} */ (AnyParenthesizedExpression); 


LEE fo * x 


在 TypeScript 2.5 中 使 用 Node 模块 解析 策略 进行 导入 时 ， 编 译 器 现在 会 检查 文件 
是 否 来 自 "相同 " 的 包 。 如 果 一 个 文件 所 在 的 包 的 package.json 包含 了 与 之 前 读 
取 的 包 相 同 的 name 和 version ， 那 么 TypeScript 会 将 它 重 定 向 到 最 顶层 的 包 


这 可 以 解决 两 个 包 可 能 会 包含 相同 的 类 声明 ， 但 因为 包含 private 成 员 导 致 他 们 
在 结构 上 不 兼容 的 问题 


这 也 带 来 一 个 额外 的 好 处 ， 可 以 通过 避免 从 重复 的 包 中 加 载 .d.ts 文件 减少 内 存 
使 用 和 编译 器 及 语言 服务 的 运行 时 计算 . 


- -preserveSymlinks (保留 符号 链接 ) 编译 器 
选项 


TypeScript 2.57 & f preservesymlinks 选项 ， 它 对 应 了 Node.js P -- 
preserve-symlinks 选项 的 行为 。 这 一 选项 也 会 带 来 和 Webpack 
的 resolve.symlinks 选项 相反 的 行为 (也 就 是 说 ， 将 TypeScript 
的 preserveSymlinks 选项 设置 为 true 对 应 了 将 Webpack 
的 resolve.symlinks 选项 设 为 false ， 反 之 亦 然 ) 。 

在 这 一 模式 中 ， 对 于 模块 和 包 的 引用 (比如 import 语句 和 /// «reference 
typez".." /> 指令 ) 都 会 以 相对 符号 链接 文件 的 位 置 被 解析 ， 而 不 是 相对 于 符号 
链接 解析 到 的 路 径 。 更 具体 的 例子 ， 可 以 参考 Node.js 网 站 的 文档 。 


TypeScript 2.4 


动态 导入 表达 式 


动态 的 import 表达 式 是 一 个 新 特性 ， 它 属于 ECMAScript 的 一 部 分 ， 人 允许 用 户 在 
程序 的 任何 位 置 异 步 地 请 求 某 个 模块 。 


这 意味 着 你 可 以 有 条 件 地 延迟 加 载 其 它 模 块 和 库 。 例 如 下 面 这 个 async 函数 ， 它 
仅 在 需要 的 时 候 才 导 入 工具 库 : 


async function getZipFile(name: string, files: File[]): Promise< 
File> { 
const zipUtil = await import('./utils/create-zip-file'); 
const zipContents - await zipUtil.getContentAsBlob(files); 
return new File(zipContents, name); 


许多 bundlers 工 具 已 经 支持 依照 这 些 import 表达 式 自动 地 


分 割 输 出 ， 因 此 可 以 考 
虑 使 用 这 个 新 特性 并 把 输出 模块 目标 设置 为 esnext 。 


> kk ` 
字符 串 枚 举 
TypeScript 2.4 现 在 支持 枚 举 成 员 变量 包含 字符 串 构造 器 。 
enum Colors { 
Red 二 PRED 


Green = "GREEN", 
Blue = "BLUE", 


需要 注意 的 是 字符 串 枚 举 成 员 不 能 被 反 向 映射 到 枚 举 成 员 的 名 字 。 d& 6) dE C > WA 
能 使 用 Colors["RED"] 来 得 到 "Red" 。 


增强 的 泛 型 推断 


TypeScript 2.4 围 绕 着 泛 型 的 推断 方式 引入 了 一 些 很 棒 的 改变 。 


返回 类 型 作为 推断 目标 


其 一 ，TypeScript 能 够 推断 调用 的 返回 值 类 型 。 这 可 以 优化 你 的 体验 和 方便 捕获 错 
误 。 如 下 所 示 : 


function arrayMap<T, U>(f: (x: T) => U): (a: T[]) => U[] { 
return a => a.map(f); 


const lengths: (a: string[]) => number[] = arrayMap(s => s.lengt 
h); 


下 面 是 一 个 你 可 能 会 见 到 的 出 错 了 的 例子 : 


let x: Promise<string> = new Promise(resolve => { 
resolve(i0); 
Ht if ses ECON! 


3); 


从 上 下 文 类 型 中 推断 类 型 参数 
在 TypeScript 2.4 之 前 ， 在 下 面 的 例子 里 : 


let f: <T>(x: T) => T = y => y; 


y 将 会 具有 any 类 型 。 这 意味 着 虽然 程序 会 检查 类 型 ， 但 是 你 却 可 以 使 用 y 做 
任何 事情 ， 就 比如 : 


let f: <T>(x: T) => T = y => y() + y.foo.bar; 


这 个 例子 实际 上 并 不 是 类 型 安全 的 。 


在 TypeScript 2.4 里 ， 右 手边 的 函数 会 隐 式 地 获得 类 型 参数 ， 并 且 y 的 类 型 会 被 推 
断 为 那个 类 型 参数 的 类 型 。 


如 果 你 使 用 y 的 方式 是 这 个 类 型 参数 所 不 支持 的 ， 那 么 你 会 得 到 一 个 错误 。 在 这 
MAFE> THAR G (BA) ， 所 以 在 最 后 一 个 例子 里 会 出 错 。 


对 泛 型 函数 进行 更 严格 的 检查 


TypeScript 在 比较 两 个 单一 签名 的 类 型 时 会 尝试 统一 类 型 参数 。 因此， 在 涉及 到 两 
个 泛 型 签名 的 时 候 会 进行 更 严格 的 检查 ， 这 就 可 能 发 现 一 些 bugs。 


type A = <T, U>(x: T, y: U) => [T, U]; 
type B = <S>(x: S, y: S) => [S, S]; 


FUNncCELOon Tlas A, bs B) 
a=b; // Error 
b =a; // Ok 


回调 参数 的 严格 抗 变 


TypeScript 一 直 是 以 双 变 (bivariant) 的 方式 来 比较 参数 。 这 样 做 有 很 多 原因 ， 总 
体 上 来 说 这 不 会 有 什么 大 问题 直到 我 们 发 现 它 应 用 在 Promise 和 Observable 上 
时 有 些 副作用 。 


TypeScript 2.4 在 处 理 两 个 回调 类 型 时 引入 了 收 紧 机 制 。 例 如 : 


interface Mappable<T> ( 
map<U>(f: (x: T) => U): Mappable<U>; 


declare let a: Mappable<number>; 
declare let b: Mappable<string | number»; 


a-b; 
b-a; 


在 TypeScript 2.4 之 前 ， 它 会 成 功 执行 。 当 关联 map 的 类 型 时 ，TypeScript 会 双向 
地 关联 它们 的 类 型 (例如 f 的 类 型 ) 。 当 关 联 每 个 f 的 类 型 时 ，TypeScript 也 会 
双向 地 关联 那些 参数 的 类 型 。 


TS 2.4 里 关联 map 的 类 型 时 ，TypeScript 会 检查 否 每 个 参数 都 是 回调 类 型 ， 如 果 


是 的 话 ， 它 会 确保 那些 参数 根据 它 所 在 的 位 置 * (contravariant) 地 方式 进行 
检查 o 


换 句 话说 ，TypeScript 现 在 可 以 捕获 上 面 的 bug， 这 对 某 些 用 户 来 说 可 能 是 一 个 破坏 
性 改动 ， 但 却 是 非常 帮助 的 。 


弱 类 型 (Weak Type) 探测 


TypeScript 2.4 引 入 了 " 弱 类 型 "的 概念 。 任何 只 包含 了 可 选 属性 的 类 型 被 当 作 
是 “Weak”。 比 如， 下 面 的 Options 类 型 是 弱 类 型 : 


interface Options { 
data?: string, 
timeout?: number, 
maxRetries?: number, 


在 TypeScript 2.4 里 给 弱 类 型 赋值 时 ， 如 果 这 个 值 的 属性 与 弱 类 型 的 属性 没有 任何 重 
登 属性 时 会 得 到 一 个 错误 。 比如 : 


function sendMessage(options: Options) { 
A ee 


const opts = { 
payload: "hello world!", 
retryOnFail: true, 


} 

// 错误 ! 

sendMessage(opts); 

// 'opts' 和 'Options' RA £ & 1414 

// 可 能 我 们 想 要 用 'data'/'maxRetries' 来 代 蔡 'payload'/'retryOnFail' 


因为 这 是 一 个 破坏 性 改动 ， 你 可 能 想 要 知道 一 些 解决 方法 : 


1. 确定 属性 存在 时 再 声明 


2. 给 弱 类 型 增加 索引 签名 (比如 [propName: string]: {} ) 
3. 使 用 类 型 断言 (比如 opts as Options ) 


TypeScript 2.3 
ES5/ES3 的 生成 器 和 迭代 支持 


首先 是 一 些 ES2016 的 术语 : 
迭代 器 


ES20155] A f Iterator CRZ) ， 它 表示 提供 了 next，return， 以 及 throw 
三 个 方法 的 对 象 ， 具 体 满 足以 下 接口 : 


interface Iterator<T> { 
next(value?: any): IteratorResult<T>; 
return?(value?: any): IteratorResult<T>; 
throw?(e?: any): IteratorResult<T>; 


} 


这 种 迭代 器 对 于 和 迭代 可 用 的 值 时 很 有 用 ， 比 如 数组 的 元 素 或 者 Map 的 键 。 如 果 一 个 
ale 一 个 返回 Iterator 对 象 的 Symbol.iterator 方法 ， 那 么 我 们 说 这 个 对 象 
是 “可 和 迭代 的 ”。 


和 迭代 器 协议 还 定义 了 一 些 ES2015 中 的 特性 像 for. .of 和 展开 运算 符 以 及 解构 赋值 
中 的 数组 的 剩余 运算 的 操作 对 象 。 


ES2015 也 引入 了 "生成 器 "， 生 成 器 是 可 以 通过 Iterator 接口 和 yield 关键 字 被 
用 来 生成 部 分 运算 结果 的 函数 。 生 成 器 也 可 以 在 内 部 通过 yield* 代理 对 与 其 他 可 
和 迭代 对 象 的 调用 。 举 例 来 说 : 


FURECELON i) T 
yield 1; 
yield* [2, 3]; 

j 


新 的 --downlevellteration 编译 选项 


之 前 和 迭代 器 只 在 编译 目标 为 ES6/ES2015 或 者 更 新 版 本 时 可 用 。 此 外 ， 设 计 和 迭代 器 
协议 的 结构 ， 比 如 for..of ， 如 果 编 译 目 标 低 于 ES6/ES2015， 则 只 能 在 操作 数 
组 时 被 支持 。 


TypeScript 2.3 在 ES3 - s 为 编译 目标 时 由 --downlevelIteration 编译 选项 
增加 了 完整 的 对 生成 器 器 协议 的 支持 。 


通过 --downlevelIteration 编译 选项 ， 编 译 器 会 使 用 新 的 类 型 检查 和 输出 行 
为 ， 尝 试 调用 被 迭代 对 象 的 [Symbol.iterator]() 方法 (如 果 有 )， 或 者 在 对 象 上 
创建 一 个 语义 上 的 数组 迭代 器 


注意 这 需要 非 数 组 的 值 有 原生 的 Symbol.iterator 或 
者 Symbol.iterator 的 运行 时 模拟 实现 。 


使 用 --downlevelIteration 时 ， 在 ES5/ES3  for..of 语句、 数组 解构 、 数 
APAREA BRAAM ` new 表达 式 在 支持 Symbol.iterator 时 可 用 ， 但 即 
便 没 有 定义 Symbol.iterator ， 它 们 在 运行 时 或 开发 时 都 可 以 被 使 用 到 数组 上 . 


异步 迭代 
TypeScript 2.3 添加 了 对 异步 和 生成 器 的 支持 ， 描 述 见 当前 的 TC39 提案 。 
异步 迭代 器 


异步 迭代 引入 了 AsyncIterator ， 它 和 Iterator 相似 。 实 际 上 的 区 别 在 

于 AsyncIterator 的 next ^ return 和 throw 方法 的 返回 的 是 迭代 结果 

的 Promise ， 而 不 是 结果 本 身 。 这 允许 AsyncIterator 在 生成 值 之 前 的 时 间 点 
就 加 入 蜡 步 通知 。 AsyncIterator 的 接口 如 下 : 


interface AsyncIterator<T> { 
next(value?: any): Promise<IteratorResult<T>>; 
return?(value?: any): Promise<IteratorResult<T>>; 
throw?(e?: any): Promise<IteratorResult<T>>; 


一 个 支持 异步 迭代 的 对 象 如 果 有 一 个 返回 AsyncIterator 4H 
的 Symbol.asyncIterator 方法 ， 被 称 作 是 “可 和 迭代 的 ”。 


$ 


步 生 成 器 


dps AT dua 成 器 ”， 也 就 是 可 以 用 来 生成 部 分 计算 结果 的 异步 
数 。 异 步 生 成 器 也 可 以 通过 yield* 代理 对 可 和 迭代 对 象 或 异步 可 和 挝 eran 


async function* g() { 

yield 1; 

await sleep(100); 

yaeld* r2 3] 

yield* (async function *() ( 
await sleep(109); 
yield 4; 

3)0; 


fe E MAH JE ENS 6E BREA RARAN’ AX PARS «gsx 
方法 。 箭 头 函 数 不 能 作为 异步 生成 器 。 A es 

的 Symbol.asyncIterator 引用 外 (原生 或 三 方 实现 )， 还 需要 一 个 可 用 的 全 

局 Promise 实现 〈 既 可 以 是 原生 的 ， 也 可 以 是 ES2015 兼 容 的 实现 ) 。 


for-await-of 7 4) 
最 后 ，ES2015 引 入 了 for..of a JX 3E ANT RRA Ro MWAH > HDR REE GS 
入 了 for..await..of 语 名 来 迭代 可 弄 步 迭代 的 对 象 。 


async function f() { 
for await (const x of g()) { 
console.log(Xx); 


for..await..of 语句 仅 在 异步 函数 或 异步 生成 器 中 可 用 。 
注意 事项 


e. 始终 记 住 我 们 对 于 措 步 迭 代 器 的 支持 是 建立 在 运行 时 
有 Symbol.asyncIterator - o 。 你 可 能 需 
要 Symbol.asyncIterator 的 三 方 实现 ， 虽 然 对 于 简单 的 目的 可 以 仅仅 


日 


zt: (Symbol as any).asyncIterator = Symbol.asyncIterator | | 
Symbol.for("Symbol.asyncIterator"); 

e 如 果 你 没有 声明 AsyncIterator ， 还 需要 在 --lib 选项 中 加 入 esnext 来 
获取 AsyncIterator 声明 。 

e 最 后 , 如 果 你 的 编译 目标 是 ES5 或 ES3， 你 还 需要 设置 -- 
downlevellterators 编译 选项 。 


泛 型 参数 默认 类 型 
TypeScript 2.3 增加 了 对 声明 泛 型 参数 默认 类 型 的 支持 。 


示例 


考虑 一 个 会 创建 新 的 HTMLElement 的 元 数 ， 调 用 时 不 加 参数 会 生成 一 个 Div ， 
你 也 可 以 选择 性 地 传 入 子 元 素 的 列表 。 之 前 你 必须 这 么 去 定义 : 


declare function create(): Container<HTMLDivElement, HTMLDivElem 
ent[]»; 

declare function create<T extends HTMLElement>(element: T): Cont 
ainer<T, T[]>; 

declare function create<T extends HTMLElement, U extends HTMLEle 
ment>(element: T, children: U[]): Container<T, U[]>; 


有 了 泛 型 参数 默认 类 型 9 我 们 可 以 将 定义 化 简 为 : 


declare function create<T extends HTMLElement = HTMLDivElement, 
U = T[]»(element?: T, children?: U): Container<T, U>; 
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e. 有 默认 类 型 的 类 型 参数 被 认为 是 可 选 的 。 

e 必 选 的 类 型 参数 不 能 在 可 选 的 类 型 参数 后 。 

o 如 果 类 型 参数 有 约束 ， 类 型 参数 的 默认 类 型 必须 满足 这 个 约束 。 

e 当 指 定 类 型 实 参 时 ， 你 只 需要 指定 必 选 类 型 参数 的 类 型 实 参 。 未 指定 的 类 型 参 
数 会 被 解析 为 它们 的 默认 类 型 。 

e 如 果 指 定 了 默认 类 型 ， 且 类 型 推断 无 法 选择 一 个 候选 类 型 ， 那 么 将 使 用 默认 类 
型 作为 推断 结果 。 


e 一 个 被 现 有 类 或 接口 合并 的 类 或 者 接口 的 声明 可 以 为 现 有 类 型 参数 引入 默认 类 
型 。 

© 一 个 被 现 有 类 或 接口 合并 的 类 或 者 接口 的 声明 可 以 引入 新 的 类 型 参数 ， 只 要 它 
指定 了 默认 类 型 。 


新 的 --strict 主要 编译 选项 


oe. 了 避免 不 兼容 现 有 项 目 通常 都 是 默认 关闭 的 。 虽 然 避 
免 不 兼容 是 好 事 ， 但 这 个 策略 的 一 个 兽 端 则 是 使 配置 最 高 类 型 安全 越 来 越 复杂 ， 这 
MATHESON EHE LIRE AAA AT -atrist it 
项 ， 就 可 以 选择 最 高 级 别 的 类 型 安全 (了 解 随 着 更 新 版 本 的 编译 器 增加 了 增强 的 类 
NRERETRARM ORR) « 


新 的 --strict 编译 器 选项 包含 了 一 些 建议 配置 的 类 型 检查 选项 。 具 体 来 说 ， 指 
定 --strict 相当 于 是 指定 了 以 下 所 有 选项 (未 来 还 可 能 a 项 ) 


e --strictNullChecks 
e --noImplicitAny 
e --noImplicitThis 


e --alwaysStrict 
确切 地 说 ， --strict 编译 选项 会 为 以 上 列 出 的 编译 器 选项 设置 默认 值 。 这 意味 着 
还 可 以 单独 控制 这 些 选项 。 比 如 : 


--strict --noImplicitThis false 


这 将 是 开启 除 --noImplicitThis 编译 选项 以 外 的 所 有 严格 检查 选项 。 使 用 这 个 
aimee 余 某 些 明确 列 出 的 项 以 外 的 所 有 严格 检查 项 。 换 名 话说 ， 现 在 可 以 在 
默认 最 高 级 别 的 类 型 安全 下 排除 部 分 检查 。 


从 TypeScript 2.3 开 始 ， tsc --init 生成 的 默 
ik tsconfig.json 在 "compilerOptions" 中 包含 了 "strict: true" 设置 。 
这 样 一 来 ， 用 tse --init 创建 的 新 项 目 默 认 会 开启 最 高 级 别 的 类 型 安全 。 


改进 的 --init 输出 


除了 默认 的 --strict 设置 外 ， tsc --init 还 改进 了 输出 。 tsc --init 默认 

生成 的 tsconfig.json 文件 现在 包含 了 一 些 带 描述 的 被 注释 掉 的 常用 编译 器 选项 . 

ea 医 得 期 望 的 结果 。 我 们 硕 望 新 的 输出 能 简化 新 项 目的 
置 并 且 随 着 项 目 成 长 保持 配置 文件 的 可 读 性 。 


- -checkJS 选项 下 js 文件 中 的 错误 


即便 使 用 了 --allowJs ，TypeScript 编 译 器 默认 不 会 报 .js 文件 中 的 任何 错误 。 
TypeScript 2.3 中 使 用 --checkJs 选项 ， .js 文件 中 的 类 型 检查 错误 也 可 以 被 报 
B. 


你 可 以 通过 为 它们 添加 // Qts-nocheck 注释 来 跳 过 对 某 些 文件 的 检查 ， 反 过 来 
你 也 可 以 选择 通过 添加 // Qts-check 注释 只 检查 一 些 .js is 件 而 不 需要 设 置 - 
-checkJs 编译 选项 。 你 也 可 以 通过 添加 // Qts-ignore 到 特定 行 的 一 行 前 来 忽 
略 这 一 行 的 错误 . 


.js 文件 仍然 会 被 检查 确保 只 有 标准 的 ECMAScript 特性 ， 类 型 标注 仅 在 .ts X 
件 中 被 允许 ， 在 .js 中 会 被 标记 为 错误 。JSDoc 注 释 可 以 用 来 为 你 的 JavaScript 代 
码 添 加 某 些 类 型 信息 ， 更 多 关于 支持 的 JSDoc 结 构 的 详情 ， 请 浏览 JSDoc 支 持 文 
档 。 


有 关 详 细 人 信息， 请 浏览 类 型 检查 JavaScript 文 件 文档 。 


TypeScript 2.2 
支持 混合 类 


TypeScript 2.2 增加 了 对 ECMAScript 2015 混合 类 模式 ( 见 MDN 混 合 类 的 描述 及 
JavaScript% "ARS E 8. Z) 以 及 使 用 交叉 来 类 型 表达 结合 混合 构造 函数 的 签 
名 及 常规 构造 函数 签名 的 规则 . 


首先 是 一 些 术 语 


混合 构造 函数 类 型 指 仅 有 单个 构造 函数 签名 ， 且 该 签名 仅 有 一 个 类 型 为 any[] HE 
长 参数 ， 返 回 值 为 对 象 类 型 . 比如 , 有 X 为 对 象 类 型 , new (...args: any[]) => X 是 一 
个 实例 类 型 为 X 的 混合 构造 函数 类 型 。 


混合 类 指 一 个 extends (扩展 ) 了 类 型 参数 类 型 的 表达 式 的 类 声明 或 表达 式 . 以 下 规 
jh] | 对 混合 RP 8]i& 


e extends 表达 式 的 类 型 参数 类 型 必须 是 混合 构造 函数 . 
e. 混合 类 的 构造 函数 (如 果 有 ) 必须 有 且 仅 有 一 个 类 型 为 any[] 的 变 长 参数 , 并 
且 必 须 使 用 展开 运算 符 在 super(...args) 调用 中 将 这 些 参数 传递 。 


假设 有 类 型 参数 为 T 且 约 束 为 X 的 表达 式 Bas ， 处 理 混 合 类 class C extends 
Base {...} 时 会 假设 Base A X 类 型 ， 处 理 结果 为 交叉 类 型 typeof C & T ° 
换言之 ， 一 个 混合 类 被 表达 为 混合 类 构造 函数 类 型 与 参数 基 类 构造 函数 类 型 的 交 又 
RA, 


在 获取 一 个 包含 了 混合 构造 函数 类 型 的 交 又 类 型 的 构造 函数 签名 时 ， 混 合 构 造 函 数 
签名 会 被 丢弃 ， 而 它们 的 实例 类 型 会 被 混合 到 交 又 类 型 中 其 ee 
类 型 中 . 比如 ， 交 又 类 型 { new(...args: any[]) => A ) & ( new(s: string) 
=> B } 仅 有 一 个 构造 函数 签名 new(s: string) =>A&B。 


ah 


将 以 上 规则 放 到 一 个 例子 中 


class Point { 
constructor (public x: number, public y: number) {} 


class Person { 
constructor (public name: string) {} 


type Constructor<T> = new(...args: any[]) => T; 


function Tagged<T extends Constructor<{}>>(Base: T) { 
return class extends Base { 
_tag: string; 
constructor(...args: any[]) { 
super(...args); 
this. tag = ""; 


const TaggedPoint = Tagged(Point); 


let point = new TaggedPoint(10, 20); 
point._tag = "hello"; 


class Customer extends Tagged(Person) { 
accountBalance: number; 


let customer = new Customer("Joe"); 
customer._tag = "test"; 
customer.accountBalance = 0; 


混合 类 可 以 通过 在 类 型 参数 中 限定 构造 函数 签名 的 返回 值 类 型 来 限制 它们 可 以 被 混 
入 的 类 的 类 型 。 举 例 来 说 ， 下 面 的 WithLocation 有 子 数 实现 了 一 个 为 满 

AX Point 接口 (也 就 是 有 类 型 为 number 的 x 和 y 属性 ) 的 类 添 

加 getLocation 方法 的 子 类 工厂 。 


interface Point { 
x: number; 
y: number; 


const WithLocation = «T extends Constructor<Point>>(Base: T) => 
class extends Base ( 
getLocation(): [number, number] { 
return [this.x, this.y]; 


object 类 型 


TypeScript 没 有 表示 非 基 本 类 型 的 类 型 ， 即 不 是 number | string | boolean | 
symbol | null | undefined 的 类 型 。 一 个 新 的 object 类 型 登场 。 


使 用 object 类 型 ， 可 以 更 好 地 表示 类 似 Object.create 这 样 的 APl。 例 如 : 
declare function create(o: object | null): void; 


create({ prop: 0 }); // OK 
create(null); // OK 


create(42); // Error 
Greate("string" ); 77 Error 
create(false); // Error 
create(undefined); // Error 


X4 new.target 


new.target 元 属性 是 ES2015 引 入 的 新 语法 。 当 通过 new 构造 函数 创建 实例 
时 ， new.target 的 值 被 设置 为 对 最 初 用 于 分 配 实例 的 构造 函数 的 引用 。 如 果 一 
个 函数 不 是 通过 new 构造 而 是 直接 被 调用 ， 那 么 new.target 的 值 被 设置 

为 undefined 。 


当 在 类 的 构造 函数 中 需要 设 
置 Object.setPrototypeOf 或 proto 时 ，new.target 就 派 上 用 场 了 。 
在 NodeJS v4 及 更 高 版 本 中 继承 Error 类 就 是 这 样 的 使 用 案例 。 


示例 


class CustomError extends Error { 


constructor(message?: string) { 
super(message); // 'Error' breaks prototype chain here 


Object.setPrototypeOf(this, new.target.prototype); // re 


store prototype chain 


j 


生成 JS 代码 : 


var CustomError = (function ( super) ( 
. extends(CustomError, super); 
tunction CustomError() A 
var _newTarget = this.constructor; 
var this = super.apply(this, arguments); // 'Error' break 
s prototype chain here 
this. proto = 
chain 
return this; 


_newTarget.prototype; // restore prototype 


j 


return CustomError; 
}) (Error); 


new.target 也 适用 于 编写 可 构造 的 部 数 ， 例 如 : 


function f() t 
if (new.target) ( /* called via 'new' */ } 


编译 为 : 


function f() { 

var _newTarget = this && this instanceof f ? this.constructor 
= VOrd 9 

if ( newTarget) ( /* called via 'new' */ } 
j 


更 好 地 检查 表达 式 的 操作 数 中 的 null / 


undefined 


TypeScript 2.2 改 进 了 对 表达 式 中 可 空 操作 数 的 检查 。 具 体 来 说 ， 这些 现在 被 标记 为 


错误 : 


e 如 果 + 运算 符 的 任何 一 个 操作 数 是 可 空 的 ， 并 且 两 个 操作 数 都 不 
是 any 或 string 类 型 。 
e wR? Mee? een? ee: EN: LE] > ee, ee, M8 或 [运算 
符 的 任何 一 个 操作 数 是 可 空 的 。 
e wR < > >>? <= ，>= 或 in 运算 符 的 任何 一 个 操作 数 是 可 空 的 。 
e 如 果 instanceof 运算 符 的 右 操作 数 是 可 空 的 。 
e 如 果 一 元 运算 符 +>? -> ~ ，++ 或 者 -- 的 操作 数 是 可 空 的 。 


如 果 操 作 数 的 类 型 是 null 或 undefined 或 者 包含 null 或 undefined 的 联合 
类 型 ， 则 操作 数 视 为 可 空 的 。 注 意 : 包含 null 或 undefined 的 联合 类 型 只 会 出 
现在 --strictNullChecks 模式 中 ， 因 为 常规 类 型 检查 模式 

下 null 和 undefined 在 联合 类 型 中 是 不 存在 的 。 


字符 串 索 引 签名 类 型 的 点 属性 


具有 字符 串 索 引 签 名 的 类 型 可 以 使 用 D] 符号 访问 ， 但 不 允许 使 用 . 符号 访问 。 
从 TypeScript 2.2 开 始 两 种 方式 都 允许 使 用 。 


interface StringMap<T> { 
k stranger 
const map: StringMap<number>; 


map["propi"] = 1; 
map.prop2 = 2; 


这 仅 适 用 于 具有 显 式 字符 串 索引 签名 的 类 型 。 在 类 型 使 用 上 使 用 . 符号 访问 未 知 
属性 仍然 是 一 个 错误 。 


支持 在 JSX 子 元 素 上 使 用 扩展 运算 符 


TypeScript 2.2 增 加 了 对 在 JSX 子 元 素 上 使 用 扩展 运算 符 的 支持 。 更 多 详情 请 
看 facebook/jsx#57。 


示例 


function Todo(prop: { key: number, todo: string }) { 
return <div>{prop.key.toString() + prop.todo}</div>; 


function TodoList({ todos }: TodoListProps) { 
return <div> 
{...todos.map(todo => <Todo key={todo.id} todo={todo.tod 
0j />)} 


</div>; 


let x: TodoListProps; 


<TodoList {...x} /> 


新 的 jsx: react-native 


React-native 构 建 管道 期 望 所 有 文件 都 具有 .js 扩展 名 ， 即 使 该 文件 包含 JSX 语 法 。 
新 的 --jsx 编译 参数 值 react-native 将 在 输出 文件 中 坚持 JSX 语 法 ， 但 是 给 它 
一 个 ,js 扩展 名 。 


TypeScript 2.1 


keyof 和 查找 类 型 


在 JavaScript 中 属性 名 称 作 为 参数 的 API 是 相当 普遍 的 ， 但 是 到 目前 为 止 还 没有 表达 
在 那些 API 中 出 现 的 类 型 关系 。 


输入 索引 类 型 查询 或 keyof ， 索 引 类 型 查询 keyof T 产生 的 类 型 是 T 的 属性 名 
称 。 keyof T 的 类 型 被 认为 是 string 的 子 类 型 。 


示例 


interface Person { 
name: string; 
age: number; 
location: string; 


j 

type K1 = keyof Person; // "name" | "age" | "location" 

type K2 - keyof Person[]; // "length" | "push" | "pop" | "conca 
EN | 


type K3 = keyof { [x: string]: Person }; // string 


与 之 相对 应 的 是 索引 访问 类 型 ， 也 称 为 查找 类 型 。 在 语法 上 ， 它 们 看 起 来 像 元 素 访 
问 ， 但 是 写成 类 型 : 


示例 


type Pi = Person["name"]; // string 

type P2 = Person["name" | "age"]; // string | number 

type P3 = string["charAt"]; // (pos: number) => string 

type P4 = string[]["push"]; // (...items: string[]) => number 
type PS = string[][0]; 7 string 


你 可 以 将 这 种 模式 和 类 型 系统 的 其 它 部 分 一 起 使 用 ， 以 获取 类 型 安全 的 查找 。 


function getProperty<T, K extends keyof T>(obj: T, key: K) { 
return obj[key]; // 推断 类 型 是 T[K] 


function setProperty<T, K extends keyof T>(obj: T, key: K, value 
: T[K]) { 
obj[key] = value; 


let x = { foo: 10, bar: “hello!” }; 


let foo = getProperty(x, "foo"); // number 
let bar 


getProperty(x, "bar"); // string 


let oops = getProperty(x, "wargarbl"); // 错误 1"wargarb17" 不 存在 "f 
oo" | "bar"? 


setProperty(x, "foo", "string"); // 错误 ! ， 类 型 是 number 而 非 Sstring 


映射 类 型 


一 个 常见 的 任务 是 使 用 现 有 类 型 并 使 其 每 个 属性 完全 可 选 。 假 设 我 们 有 一 


个 Person 


interface Person { 
name: string; 
age: number; 
location: string; 


Person 的 可 选 属 性 类 型 将 是 这 样 : 


interface PartialPerson { 
name?: string; 
age?: number; 
location?: string; 


使 用 映射 类 型 PartialPerson 可 以 写成 是 Person 类 型 的 广义 变换 : 


type Partial<T> = ( 
[P in keyof T]?: T[P]; 
3 


type PartialPerson = Partial<Person>; 


映射 类 型 是 通过 使 用 字面 量 类 型 的 集合 而 生成 的 ， 并 为 新 对 象 类 型 计算 一 组 属性 。 
它们 就 像 Python 中 的 列表 推导 式 ， 但 不 是 在 列表 中 产生 新 的 元 素 ， 而 是 在 类 型 中 产 
生 新 的 属性 。 


除 Partial 外 ， 映 射 类 型 可 以 表示 许多 有 用 的 类 型 转换 : 


// 保持 类 型 相同 ， 但 每 个 属性 是 只 读 的 
type Readonly<T> = { 

readonly [P in keyof T]: T[P]; 
J; 


// 相同 的 属性 名 称 ， 但 使 值 是 一 个 Promise， 而 不 是 一 个 具体 的 值 
type Deferred<T> = { 

[P in keyof T]: Promise<T[P]>; 
H 


// 为 T 的 属性 添加 代理 
type Proxify<T> = { 

[P in keyof T]: { get(): T[P]; set(v: T[P]): void } 
3 


Partial , Readonly , Record 和 Pick 


Partial 和 Readonly ， 如 前 所 述 ， 是 非常 有 用 的 结构 。 你 可 以 使 用 它们 来 描述 
像 一 些 常见 的 JS 程序 


FUNCELON assignsale(oby. 1, props: Partial<i-—): void: 
function freeze<T>(obj: T): Readonly<T>; 


因此 ， 它 们 现在 默认 包含 在 标准 库 中 。 


我 们 还 包括 两 个 其 他 实用 程序 类 型 : Record 和 Pick 。 


// 从 T 中 选取 一 组 属性 K 
declare function pick<T, K extends keyof T>(obj: T, ...keys: KJ] 
ICUPICKST Ke; 


const nameAndAgeOnly = pick(person, "name", "age"); // { name: 


string, age: number } 


// 对 于 类 型 T 的 每 个 属性 K， 将 其 转换 为 U 
function mapobject<K extends string | number, T, U>(obj: Record< 
K, T», f: (x: T) => U): Record«K, U> 


const names = ( foo: "hello", bar: "world", baz: "bye" Y; 
const lengths = mapObject(names, s => s.length); // { foo: numb 
er, bar: number, baz: number } 


RY RERA rest Ei 
TypeScript 2.1 带 来 了 ESnext 扩 展 运算 符 和 rest 运 算 符 的 支持 。 


类 似 于 数组 扩展 ， 展 开 对 其 可 以 方便 得 到 浅 拷 贝 : 


let copy = { ...original }; 


同样 ， 您 可 以 合并 几 个 不 同 的 对 象 。 在 以 下 示例 中 ， 合 并 将 具有 来 
自 foo ， bar 和 baz 的 属性 。 


let merged = { ...foo, ...bar, ...baz }; 


还 可 以 重 写 现 有 属性 并 添加 新 属性 . : 


let obj = 4 xXx: 1, y: “string” y; 
var newObj = {...obj, z: 3, y: 4}; // { x: number, y: number, z: 
number } 


指定 展开 操作 的 顺序 确定 哪些 属性 在 最 终 的 结果 对 象 中 。 相 同 的 属性 ， 后 面 的 属性 
会 “ 复 盖 ?前 面 的 属性 。 


与 对 象 扩 展 运算 符 相 对 的 是 对 象 rest 运 算 符 ， 因 为 它 可 以 提取 解构 元 素 中 剩余 的 元 
* 


let obj = { x: 1, yr 4, zt 3 
let d Ay ..-0bT]1 } = obj; 
0bji; // (x: number, y: number}; 


AK WR A Sy E BK 


该 特性 在 TypeScript 2.1 之 前 就 已 经 支持 了 ， 但 是 只 能 编译 为 ES6 或 者 ES2015 。 
TypeScript 2.1 使 其 该 特性 可 以 在 ES3 和 ES5 运 行 时 上 使 用 ， 这 意味 着 无 论 您 使 用 什 
么 环境 ， 都 可 以 使 用 它 


注 : 首先 ， 我 们 liu o 支行 时 提供 全 局 的 ECMAScript 兼 容 

性 Promise 。 这 可 能 需要 获取 Promise 的 polyfil， 或 者 依赖 运行 时 的 版 本 。 
Aero ae lib 编译 参数 ， 比 

如 "dom","es2015" 或 "dom","es2015.promise","es5" 来 确保 TypeScript 
知道 Promise 可 用 。 


示例 


tsconfig.json 


"compilerOptions": { 
"lib": dom a “es2015- promise’. "ess" 


dramaticWelcome.ts 


function delay(milliseconds: number) { 
return new Promise<void>(resolve => { 
setTimeout(resolve, milliseconds); 


3); 

async function dramaticWelcome() { 
console.log("Hello"); 
hor olet 19975-1955 oe) ft 


await delay(500); 
console. Tog. e 


console.log("World!"); 


dramaticWelcome(); 


编译 和 运行 输出 应 该 会 在 ES3/ES5 引 擎 上 产生 正确 的 行为 。 


支持 外 部 辅助 库 ( tslib ) 
TypeScript 注 入 了 一 些 辅助 函数 ， 如 继承 _extends 、JSX 中 的 展开 运算 
符 assign 和 异步 函数 awaiter ° 

以 前 有 两 个 选择 : 


1. 在 每 一 个 需要 辅助 库 的 文件 都 注入 辅助 库 或 者 
2. 使 用 --noEmitHelpers 编译 参数 完全 不 使 用 辅助 库 。 


这 两 项 还 有 竺 改进。 将 帮助 文件 捆绑 在 每 个 文件 中 对 于 试图 保持 其 包 尺 寸 小 的 客户 
而 言 是 一 个 痛 点 。 不 使 用 辅助 库 ， 那 么 客户 就 必须 自己 维护 辅助 库 。 


TypeScript 2.1 允许 这 些 辅助 库 作 为 单独 的 模块 一 次 性 添加 到 项 目 中 ， 并 且 编 译 器 
根据 需求 导入 它们 。 


首先 ， 安 装 tslib 


npm install tslib 


然后 ， 使 用 --importHelpers 编译 你 的 文件 : 


tsc --module commonjs --importHelpers a.ts 


因此 下 面 的 输入 ， 生 成 的 .js 文件 将 包含 tslib 的 导入 和 使 用 assign 辅助 
函数 替代 内 联 操作 。 


export const o = { a: 1, name: "o" }; 
export const copy = { ...o }; 


"use strasct^- 

var tslib 1 = require("tslib"); 

exports.o = ( a: 1, name: "o" }; 

exports.copy = tslib_1.__assign({}, exports.o); 


无 类 型 导入 


TypeScript 历 来 对 于 如 何 导 入 模块 过 于 严格 。 这 是 为 了 避免 输入 错误 ， 并 防止 用 户 
错误 地 使 用 模块 。 

但 是 ， 很 多 时 候 你 可 能 只 想 导 入 的 现 有 模块 ， 但 是 这 些 模块 可 能 没有 .d.ts 文 
件 。 以 前 这 是 错误 的 。 从 TypeScript 2.1 开 始 ， 这 更 容易 了 。 


使 用 TypeScript 2.1， 您 可 以 导入 JavaScript 模 块 ， 而 不 需要 类 型 声明 。 如 果 类 型 声 
8] (如 declare module "foo" { ... ) X node modules/Qtypes/foo ) 存 
在 ， 则 仍然 优先 。 


对 于 没有 声明 文件 的 模块 的 导入 ， 在 使 用 了 --normplicitAny 编译 参数 后 仍 将 被 
标记 为 错误 。 


// Succeeds if ~“node_modules/asdf/index.js 


import { x } from "asdf"; 


支持 --target ES2016 , --target 
ES2017 和 --target ESNext 


TypeScript 2.1 支 持 三 个 新 的 编译 版 本 值 --target ES2016 , --target 
ES2017 和 --target ESNext ° 


使 用 target --target ES2016 将 指示 编译 器 不 要 编译 ES2016 特 有 的 特性 ， 比 
如 ** 操作 符 。 


同样 ， --target ES2017 将 指示 编译 器 不 要 编译 ES2017 特 有 的 特性 


像 async/await ° 


--target ESNext 则 对 应 最 新 的 ES 提议 特性 支持 . 


改进 any 类 型 推断 


以 前 ， 如 果 TypeScript 无 法 确定 变量 的 类 型 ， 它 将 选择 any 类 型 。 


let x: // I& X, 'any' 
Tete rS any 
let z: any; // ŁA 'any' 


使 用 TypeScript 2.1，TypeScript 不 是 仅仅 选择 any 类 型 ， 而 是 基于 你 后 面 的 赋值 
未 推断 类 型 。 


仅 当 设置 了 --noImplicitAny 编译 参数 时 ， 才 会 启用 此 选项 。 


示例 


let x; 


// MRM IR T VAR x" 赋值 任何 你 需要 的 任何 值 。 
2 


// 在 刚 赋值 后 ，TypeScript 2.1 知道 'X' 的 类 型 是 !'() => number' » 
let y = X() 


// 感谢 ， 现 在 它 会 告诉 你 ， 你 不 能 添加 一 个 数字 到 一 个 函数 ! 


console.log(x + y); 
// 错误 ! eH '€' 不 能 应 用 于 类 型 `() => number f 'number' » 


// TypeScript 仍 然 允 许 你 给 'X7 赋 值 你 需要 的 任何 值 。 
x = "Hello world!"; 


// 并 且 现 在 它 也 知道 'x' 是 'string' 类 型 的 | 


x. toLowerCase(); 


现在 对 空 数组 也 进行 同样 的 跟踪 。 


没有 类 型 注解 并 且 初 始 值 为 [] 的 变量 被 认为 是 一 个 隐 式 的 any[] 变量 。 变 量 会 
根据 下 面 这 些 操作 x.push(value) ^ x.unshift(value) X x[n] = value 向 
其 中 添加 的 元 素来 不 断 改变 自身 的 类 型 。 


TUNC EIOM i0) 
let x = []; 
x.push(5); 
x[1] = "hello"; 
x.unshift(true); 
return x; // (string | number | boolean)[] 


function £2(0)-1f 
let x = null; 
if (cond()) { 
x= []; 
while (cond()) { 
x.push("hello"); 


j 
j 
return x 7/- sErashng[ do null 
j 
隐 式 any 错 误 


这 样 做 的 一 个 很 大 的 好 处 是 ， 当 使 用 --noImplicitAny 运行 时 ， 你 将 看 到 较 少 的 
[& X, any 错误 。 隐 式 any 错误 只 会 在 编译 器 无 法 知道 一 个 没有 类 型 注解 的 变量 的 
类 型 时 才 会 报告 。 


示例 


Functions fel) 4 


let x = []; // 错误 : 当 变 量 'X'! 类 型 无 法 确定 时 ， 它 隐 式 具有 'any[] ' 半 


Helo 


型 。 
x.push(5); 
function g() f 
xX; M MR: RS es “any [] ae 
} 


更 好 的 字面 量 类 型 推断 


字符 串 、 数 字 和 布尔 字面 量 类 型 (如 : "abc" > 1 和 true ) 之 前 仅 在 存在 显 
式 类 型 注释 时 才 被 推断 。 从 TypeScript 2.1 开 始 ， 字 面 量 类 型 总 是 推断 为 默认 值 。 


不 带 类 型 注解 的 const 变量 或 readonly 属性 的 类 型 推断 为 字面 量 初始 化 的 类 
型 。 已 经 初始 化 且 不 带 类 型 注解 的 let 变量 、 var 变量 、 形 参 或 

JE readonly 属性 的 类 型 推断 为 初始 值 的 扩展 字面 量 类 型 。 字 符 串 字面 量 扩展 类 型 
是 string ， 数 字 字面 量 扩展 类 型 是 number , true 或 false 的 字面 量 类 型 

是 boolean ， 还 有 枚 举 字 面 量 扩展 类 型 是 枚 举 。 


示例 


const cdi =1; // Type 1 

const c2 = ci; // Type 1 

const c3 = "abc"; 7/ Type "abc" 

const c4 = true; // Type true 

CONSE cb - cond ? 1$ : "abc 7 Type 1 | "abc" 


let vi = 1; // Type number 

let v2 = c2; // Type number 

let v3 = c3; // Type string 

let v4 = c4; // Type boolean 

let v5 = cb; // Type number | string 


字面 量 类 型 扩展 可 以 通过 显 式 类 型 注解 来 控制 。 具 体 来 说 ， 当 为 不 带 类 型 注解 

的 const 局 部 变量 推断 字面 量 类 型 的 表达 式 时 ， var 变量 获得 扩展 字面 量 类 型 
推断 。 但 是 当 const 局 部 变量 有 显 式 字面 量 类 型 注解 时 ， var 变量 获得 非 扩 展 
字面 量 类 型 。 


示例 


const ci = "hello"; // Widening type "hello" 
let vi = c1; // Type string 


const c2: "hello" = "hello"; // Type "hello" 
let v2 = c2; // Type "hello" 


将 基 类 构造 函数 的 返回 值 作 为 "this' 


在 ES2015 中 ， 构 造 吕 数 的 返回 值 ( 它 是 一 个 对 象 ) BAW this 的 值 替换 

为 super() 的 任何 调用 者 。 因 此 ， 有 必要 捕获 任何 潜在 的 super() 的 返回 值 并 
替换 为 this 。 此 更 改 允 许 使 用 自 定义 元 订 ， 利 用 此 元 素 可 以 使 用 用 户 编写 的 构造 
函数 初始 化 浏览 器 分 配 的 元 素 。 


示例 


class Base { 
x: number; 
constructor() { 
// ikW ts < 
return { 
xcu 
3 


class Derived extends Base ( 
constructor() { 
super(); 
Eis. x= Ae 


生成 : 


var Derived = (function ( super) { 
. extends(Derived, super); 
function Derived() ( 
var this = super.call(this) || this; 
_this.x = 2; 
return _this; 
} 
return Derived; 
}(Base)); 


这 在 继承 内 置 类 如 Error * Array * Map 等 的 行为 上 有 了 破坏 性 的 改变 。 
请 阅读 extending built-ins breaking change documentation 。 


配置 继承 


通常 一 个 项 目 有 多 个 输出 版 本 ， 比 如 ESS 和 ES2015 ， 调 试 和 生产 
或 Commonjs 和 System 。 只 有 几 个 配置 选项 在 这 两 个 版 本 之 间 改 变 ， 并 且 维 护 
多 个 tsconfig.json 文件 是 麻烦 的 。 


TypeScript 2.1 支 持 使 用 extends 来 继承 配置 ， 其 中 : 


e extends 在 tsconfig.json 是 新 的 顶级 属性 
(与 compilerOptions ^ files ^ include 和 exclude 一 起 ) 。 
e extends 的 值 是 包含 继承 自 其 它 tsconfig.json 路 径 的 字符 串 。 
e 首先 加 载 基本 文件 中 的 配置 ， 然 后 由 继承 配置 文件 重 写 。 
e 如 果 遇 到 循环 ， 我 们 报告 错误 。 
e 继承 配置 文件 中 的 files ^ include 和 exclude 会 重 写 基本 配置 文件 中 相 
应 的 值 
e 在 配置 文件 中 找到 的 所 有 相对 路 径 将 相对 于 它们 来 源 的 配置 文件 来 解析 o 


示例 


configs/base.json : 


{ 

"compilerOptions": { 
"allowJs": true, 
"noImplicitAny": true, 
"strictNullChecks": true 

} 

} 


configs/tests.json : 


TypeScript 2.1 


"compilerOptions": { 
"preserveConstEnums": true, 
"stripComments": false, 
"sourceMaps": true 

tr 

"exclude": [ 
"../tests/baselines", 
"../tests/scenarios" 

], 

"include": [ 

Wu Abest ES 


tsconfig.json : 


{ 
"extends": "./configs/base", 
pales 
"main.ts", 
"supplemental.ts" 
] 
} 


tsconfig.nostrictnull.json : 


{ 
"extends": "./tsconfig", 
"compilerOptions": ( 
"strictNullChecks": false 
} 
} 


新 编译 参数 --alwaysStrict 


483 


使 用 --alwaysstrict 调用 编译 器 原因 : 1. 在 严格 模式 下 解析 的 所 有 代码 。2. 在 每 
一 个 生成 文件 上 输出 "use strict"; 指令 ; 


模块 会 自动 使 用 严格 模式 解析 。 对 于 非 模块 代码 ， 建 议 使 用 该 编译 参数 。 


TypeScript 2.0 


Null- undefined 3 7? 


TypeScript 现 在 有 两 个 特殊 的 类 型 NullfeUndefined, E11 4944 > 9 
是 null 和 undefined 。 以 前 这 是 不 可 能 明确 地 命名 这 些 类 型 的 ， 但 是 现 
在 null 和 undefined 不 管 在 什么 类 型 检查 模式 下 都 可 以 作为 类 型 名 称 使 用 。 


以 前 类 型 检查 器 认为 null 和 undefined 赋值 给 一 切 。 实 际 
上 ，null 和 undefined 是 每 一 个 类 型 的 有 效 值 ， 并 且 不 能 明确 排除 它们 (因此 
不 可 能 检测 到 错误 ) o 


--strictNullChecks 


--strictNullChecks 可 以 切换 到 新 的 严格 空 检 查 模 式 中 。 


在 严格 空 检查 模式 中 ， null 和 undefined 值 不 再 属于 任何 类 型 的 值 ， 仅仅 属 于 
它们 自己 类 型 和 any 类 型 的 值 (还 有 一 个 例外 ， undefined 也 能 赋值 

给 void ) 。 因 此 ， 尽 管 在 常规 类 型 检查 模式 下 T 和 T | undefined 被 认为 是 
相同 的 (AA undefined 被 认为 是 任何 T 的 子 类 型 ) ， 但 是 在 严格 类 型 检查 模 
式 下 它们 是 不 同 的 ， 并 且 仅 仅 T | undefined 允许 有 undefined 值 ，T fe T 
| null 的 关系 同样 如 此 。 


示例 


Typescript 2.0 


// 使 用 --strictNullChecks 参 数 进行 编译 的 


let 
let 


N NX XxX X x NN OX NX x NX X 
Il 


x: number; 





y: number | undefined; 
z: number | null | undefined; 
qu SET 

1; // iE 

W E BT. 

undefined; // 错误 
undefined;  // 正确 
undefined; // 正确 
null; // 4&iX 

null; // 错误 

null; // EAA 

y V A 

Zi Wf Wu 

x; // 正确 

zi // 58A 

x; // 正确 

y; // 正确 





使 用 前 赋值 检查 


在 严格 空 检查 模式 中 ， 编 译 器 要 求 未 包含 undefined 类 型 的 局 部 变量 在 使 用 之 前 
x 2f A IAAL © 


示例 


// 使 用 --strictNullChecks 参 数 进行 编译 
let x: number; 

let y: number | null; 

let z: number | undefined; 

x; // 错误 ， 使 用 前 未 赋值 

y; // 错误 ， 使 用 前 未 赋值 


Z; // 正确 
= 1; 

y = null; 

x; // 正确 

y; // 正确 


可 选 参 数 和 属性 会 自动 把 undefined 添加 到 他 们 的 类 型 中 ， 即 使 他 们 的 类 型 注解 
明确 不 包含 undefined 。 例 如 ， 下 面 两 个 类 型 是 完全 相同 的 : 


// 使 用 --strictNullChecks 参 数 进行 编译 

type T1 = (x?: number) => string; // X 的 类 型 是 numbe 
r | undefined 

type T2 = (x?: number | undefined) => string; // x 的 类 型 是 numbe 
r | undefined 


3Enull £e 3Fundefined X: # 4&4? 

de RI RRA BAH KB AS null 和 undefined > AR Zi HA RTA BAH 
就 会 产生 编译 错误 。 因 此 ， er erem > VA E 4E 3Enullf« ZEundefined 
的 检查 。 


示例 


// 使 用 --strictNullChecks 参 数 进行 编译 
declare function f(x: number): string; 
let x: number | null | undefined; 

if (x) { 


f(x); // 正确 ， 这 里 的 X 类 型 是 number 


} 
else { 
f(x); // 错误 ， 这 里 的 X 类 型 是 number ? 
} 
let a = x != null ? f(x) s ""; // a 的 类 型 是 string 
let b = x && f(x); // b 的 类 型 是 string | © | null | undefined 


非 null 和 非 undefined 类 型 保护 可 以 使 用 == ^ 12 、 === 或 !== 操作 符 

和 null 或 undefined 进行 比较 ， 如 x != null 或 x === undefined 。 对 被 
IO 
值 无 论 你 指定 的 是 null 还 是 undefined， 然 而 三 等 于 号 运算 符 仅 仅 检 查 指 定 的 那 一 个 
值 ) 。 


类 型 保护 中 的 点 名 称 


类 型 保护 以 前 仅仅 支持 对 局 部 变量 和 参数 的 检查 。 现 在 类 型 保护 支持 检查 由 变量 或 
参数 名 称 后 跟 一 个 或 多 个 访问 属性 组 成 的 “点 名 称 ”。 


示例 


interface Options { 
location?: { 

x?: number; 

y?: number; 


H 


function foo(options?: Options) ( 
if (options && options.location && options.location.x) { 
const x = options.location.x; // x 的 类 型 是 number 


点 名 称 的 类 型 保护 和 用 户 定义 的 类 型 保护 函 还 有 typeof 和 instanceof 操 
作 符 一 起 工作 ， 并且 不 依赖 --strictNullchecks 编译 参数 。 


对 点 名 称 进 M 给 点 名 称 任 一 部 分 赋值 都 会 导致 类 型 保护 无 效 。 例 如 ， 
对 x.y.z 进行 了 类 型 保护 后 给 x ^ xy X x.y.z 赋值 ,都 会 导致 x.y.z 类 
型 保护 无 效 。 


表达 式 操作 符 


表达 式 操作 符 允 许 运算 对 象 的 类 型 包含 null 和 /或 undefined ， 但 是 总 是 产生 非 
null 和 非 undefined 类 型 的 结果 值 。 


// 使 用 --strictNullChecks 参 数 进行 编译 
function sum(a: number | null, b: number | null) { 
return a + b; // 计算 的 结果 值 类 型 是 number 


&& 操作 符 添 加 null 和 /或 undefined 到 右边 操作 对 象 的 类 型 中 取决 于 当前 左 
边 操 作对 象 的 类 型 ， || 操作 符 从 左边 联合 类 型 的 操作 对 象 的 类 型 中 
将 null 和 undefined 同时 删除 。 


ET 


/ 使 用 --strictNullChecks 参 数 进行 
interface Entity { 
name: string; 


} 
let x: Entity | null; 


let s = x && x.name; // Ss 的 类 型 是 string | null 
let y =x || { name: "test" ); // y 的 类 型 是 Entity 


类 型 扩展 
在 严格 空 检 查 模式 中 ， null 和 undefined 类 型 是 不 会 扩展 到 any 类 型 中 的 。 


let z = null; // Zz 的 类 型 是 null 


在 常规 类 型 检查 模式 中 ， 由 于 扩展 ， 会 推断 z 的 类 型 是 any ， 但 是 在 严格 空 检查 
模式 中 ， 推 断 z 是 null 类 型 (因此 ， 如 果 没 有 类 型 注释 null 是 z 的 唯一 
值 ) 。 


非 空 断言 操作 符 


在 上 下 文中 当 类 型 检查 器 无 法 断定 类 型 时 ， 一 个 新 的 后 组 表达 式 操 作 符 ! 可 以 用 
于 断言 操作 对 象 是 非 null 和 非 undefined 类 型 的 。 具 体 而 言 ， 运 算 x! 产生 一 个 不 包 
4: null 和 undefined 的 x 的 值 。 断 言 的 形式 类 似 于 <T>x 和 x as 


T > | 非 空 断言 操作 符 会 从 编译 成 的 JavaScript 代 码 中 移 除 。 


// 使 用 --strictNullChecks 参 数 进行 编译 
function validateEntity(e?: Entity) { 
// 如 果 e 是 null 或 者 无 效 的 实体 ， 就 会 抛 出 异常 


function processEntity(e?: Entity) t 


validateEntity(e); 
let s = e!.name; // 断言 e 是 非 空 并 访问 name 属 性 


兼容 性 


这 些 新 特性 是 经 过 设计 的 ， 使 得 它们 能 够 在 严格 空 检查 模式 和 常规 类 型 检查 模式 下 
都 能 够 使 用 。 尤 其 是 在 常规 类 型 检查 模式 中 ， null 和 undefined 类 型 会 自动 从 
联合 类 型 中 删除 (因为 它们 是 其 它 所 有 类 型 的 子 类 型 ) > | 非 空 断言 表达 式 操 作 
符 也 被 允许 使 用 但 是 没有 任何 作用 。 因 此 ， 声 明文 件 使 用 null 和 undefined 敏 感 类 型 
更 新 后 ， 在 常规 类 型 模式 中 仍然 是 可 以 向 后 兼容 使 用 的 。 


在 实际 应 用 中 ， 严 格 空 检查 模式 要 求 编译 的 所 有 文件 都 是 null 和 undefined 敏 感 类 


型 。 


TypeScript 2.0 实 现 了 对 局 部 变量 和 参数 的 控制 流 类 型 分 析 。 以 前 ， 对 类 型 保护 进行 
类 型 分 析 仅 限于 if 语句 和 ?: 条 件 表 达 式 ， 并 且 不 包括 赋值 和 控制 流 结构 的 影 
响 ， 例 如 return 和 break 语句 。 使 用 TypeScript 2.0， 类 型 检查 器 会 分 析 语 名 和 
表达 式 所 有 可 能 的 控制 流 ， 在 任何 指定 的 位 置 对 声明 为 联合 类 型 的 局 部 变量 或 参数 
产生 最 可 能 的 具体 类 型 (缩小 范围 的 类 型 ) © 


示例 


function foo(x: string | number | boolean) { 


if (typeof x === "string") { 
x; // 这 里 x 的 类 型 是 string 
X= 


X; // 这 里 x 的 类 型 是 number 


X; // 这 里 x 的 类 型 是 number | boolean 


function bar(x: string | number) { 
if (typeof x === "number") { 
return; 
} 


x; // OR estring 


基于 控制 流 的 类 型 分 析 在 --strictNullchecks 模式 中 尤为 重要 ， 因 为 可 空 类 型 
使 用 联合 类 型 来 表示 : 


function test(x: string | null) { 
if (x === null) { 
return; 


mE» Æ --strictNullChecks 模式 中 ， 基 于 控制 流 的 分 析 包 括 ， 对 类 型 不 允许 
为 undefined 的 局 部 变量 有 明确 赋值 的 分 析 。 


function mumble(check: boolean) { 
let x: number; // 类 型 不 允许 为 undefined 
x; // 错误 ，X 是 undefined 
if (check) { 
a= 
x; // 正确 


x; // 错误 ，X 可 能 是 undefi 
X 
X 


标记 联合 类 型 


TypeScript 2.0 实 现 了 标记 (或 区 分 ) 联合 类 型 。 具 体 而 言 ，TS 编 译 器 现在 支持 类 
型 保护 ， 基 于 判别 属性 的 检查 来 缩小 联合 类 型 的 范围 ， 并 且 switch 语句 也 支持 此 
特性 。 


示例 


interface Square { 
kind: "square"; 
size: number; 


interface Rectangle { 
kind: "rectangle"; 
width: number; 
height: number; 


interface Circle { 
kind: "circle"; 
radius: number; 


type Shape = Square | Rectangle | Circle; 


function area(s: Shape) { 
// 在 下 面 的 Switch 语句 中 ，S 的 类 型 在 每 一 个 case 中 都 被 缩小 
// 根据 判别 属性 的 值 ， 变量 的 其 它 属性 不 使 用 类 型 断言 就 可 以 被 访问 
switch (s.kind) { 
case "square": return s.size * s.size; 
case "rectangle": return s.width * s.height; 
case "circle": return Math.PI * s.radius * s.radius; 


function testi(s: Shape) { 
if (s.kind --- "square") ( 
s; // Square 


} 
else { 
$; 4/ Rectangle | Circle 
} 
} 
function test2(s: Shape) { 
if (s.kind === "square" || s.kind === "rectangle") { 
return; 
} 
S1 REG bic 
} 
判别 属性 类 型 保护 是 x.p =v 、 xp === v ^ xp != Vv 或 者 xp !=v 其 


中 的 一 种 表达 式 ，p fev 是 一 个 属性 和 字符 串 字 面 量 类 型 或 字符 串 字 面 量 联合 类 
型 的 表达 式 。 判 别 属性 类 型 保护 缩小 x 的 类 型 到 由 判别 属性 p 和 v 的 可 能 值 之 
一 组 成 的 类 型 。 

请 注意 ， 我 们 目前 只 支持 字符 串 字面 值 类 型 的 判别 属性 。 我 们 打算 以 后 添加 对 布尔 
值 和 数字 字面 量 类 型 的 支持 。 


never 类 型 


TypeScript 2.0 引 入 了 一 个 新 原始 类 型 never 。 never 类 型 表示 值 的 类 型 从 不 出 
现 。 具 体 而 言 ， never 是 永 不 返回 函数 的 返回 类 型 ， 也 是 变量 在 类 型 保护 中 永 不 
为 true 的 类 型 。 


never 类 型 具有 以 下 特征 : 


e never 是 所 有 类 型 的 子 类 型 并 且 可 以 赋值 给 所 有 类 型 。 

e 没有 类 型 是 never 的 子 类 型 或 能 赋值 给 never ( never 类 型 本 身 除 外 ) © 

e 在 函数 表达 式 或 箭头 函数 没有 返回 类 型 注解 时 ， 如 果 函 数 没 有 return 语句 ， 
或 者 只 有 never 类 型 表达 式 的 return 语句 ， 并 且 如 果 函 数 是 不 可 执行 到 终 
点 的 〈 例 如 通过 控制 流 分 析 决 定 的 ) ， 则 推断 函数 的 返回 类 型 是 never 。 

e 在 有 明确 never 返回 类 型 注解 的 函数 中 ， 所 有 return 语句 (如果 有 的 话 ) 
必须 有 never 类 型 的 表达 式 并 且 函 数 的 终点 必须 是 不 可 执行 的 。 


因为 never focos PRE PAS EGER RP UE 9 EB ER 
数 中 只 要 其 它 类 型 被 返回 ， 类 型 推断 就 会 忽略 never 类 型 。 


一 些 返回 never 函数 的 示例 : 
// 辑 数 返回 never 必 须 无 法 执行 到 终点 
function error(message: string): never { 
throw new Error(message); 


// 推断 返回 类 型 是 never 
function fail() { 
return error("Something failed"); 


// SRBEnever LA KAW A! 
Function infiniteLoop(): never { 
while (true) { 


} 


— Kk SRR E never 的 使 用 示例 : 


// 推断 返回 类 型 是 number 
function movei(direction: 
switch (direction) { 


case "up": 
return 1; 


up" | "down" ) 1 


case "down": 
return -1; 


} 
return error("Should never get here"); 
} 
// 推断 返回 类 型 是 number 
function move2(direction: "up" | "down") { 
return direction === "up" ? 1: 
direction === "down" ? -1 : 


error("Should never get here"); 


// 推断 返回 类 型 是 T 
function check<T>(x: T | undefined) { 
return x || error("Undefined value"); 


因为 never 可 以 赋值 给 每 一 个 类 型 ， 当 需要 回调 函数 返回 一 个 更 加 具体 的 类 型 
Kt > BARE never 类 型 可 以 用 于 检测 返回 类 型 是 否 正 确 : 


function test(cb: () => string) { 
let s = cb(); 
return s; 


test(() => "hello"); 
test(() => fail()); 
test(() => { throw new Error(); }) 


只 读 属 性 和 索引 签名 


属性 或 索引 签名 现在 可 以 使 用 readonly 修饰 符 声 明 为 只 读 的 。 


只 读 属性 可 以 初始 化 和 在 同一 个 类 的 构造 函数 中 被 赋值 ， 但 是 在 其 它 情况 下 对 只 读 
属性 的 赋值 是 不 允许 的 。 


此 外 ， 有 几 种 情况 下 实体 隐 式 只 读 的 : 


e 属性 声明 只 使 用 get 访问 器 而 没有 使 用 set 访问 器 被 视 为 只 读 的 。 

e 在 枚 举 类 型 中 ， 枚 举 成 员 被 视 为 只 读 属 性 。 

e 在 模块 类 型 中 ， 导 出 的 const 变量 被 视 为 只 读 属 性 。 

e ^ import 124) P P PA ig ERIA Rie AY o 

过 ES2015 命 名 空间 导入 访问 的 实体 被 视 为 只 读 的 〈 例 如 ， 当 foo d 


r import * as foo from "foo" 声明 时 ， foo.x 是 只 读 的 ) 。 


示例 


interface Point { 
readonly x: number; 
readonly y: number; 


Var p1: Point = { x: 10, y: 20 }; 
pi.x = 5; // WR? pl. x2rEN 


var p2 = { x: 1, y: 1 }; 
var p3: Point = p2; // 正确 ，p2 的 只 读 别 名 


p3.X = 5; // 错误 ，p3.Xx 是 只 读 的 
5; // 正确 ， 但 是 因为 别名 使 用 ， 同 时 也 改变 了 p3 .X 


De 


p2.x = 


class Foo { 
readonly a = 1; 
readonly b: string; 
constructor() { 
this.b = "hello"; // 在 构造 函数 中 允许 赋值 


let a: Array<number> = [0, 1, 2, 3, 4]; 
let b: ReadonlyArray<number> = a; 


b[5] = 5; // 错误 ， 元 素 是 只 读 的 

b.push(5); // 错误 ， 没 有 push 方 法 〈 因 为 这 会 修改 数组 ) 
b.length = 3: // 错误 ， nee 只 读 的 

a = b; // 错误 ， 缺 少 修 改 数 组 的 方法 


指定 函数 中 this 类 型 
紧 跟 着 类 和 接口 ， 现 在 函数 和 方法 也 可 以 声明 this 的 类 型 了 。 


HP this 的 默认 类 型 是 any 。 从 TypeScript 2.0 开 始 ， 你 可 以 提供 一 个 明确 
的 this 参数。 this 参数 是 伪 参 数 ， 它 位 于 函数 参数 列表 的 第 一 位 : 


function, FCthiss void) € 
// 确保 `this ` 在 这 个 独立 的 函数 中 无 法 使 用 


回调 函数 中 的 this 参数 


库 也 可 以 使 用 this 参数 声明 回调 函数 如 何 被 调用 。 
示例 


interface UIElement { 
addClickListener(onclick: (this: void, e: Event) => void): v 
ord. 


j 


this:void 意味 着 addClickListener 预计 onclick 是 一 个 this 参数 不 需 
要 类 型 的 函数 。 


现在 如 果 你 在 调用 代码 中 对 this 进行 了 类 型 注释 : 


class Handler { 
Info. sth ing, 
onClickBad(this: Handler, e: Event) { 


// 哎哟 ， 在 这 里 使 用 this .在 运行 中 使 用 这 个 回调 函数 将 会 崩溃 
this.info = e.message; 
3 
} 
let h = new Handler(); 
uiElement.addClickListener(h.onClickBad); // xi! 


- noImplicitThis 


TypeScript 2.0 还 增加 了 一 个 新 的 编译 选项 用 来 标记 有 函数 中 所 有 没有 明确 类 型 注释 
的 this 的 使 用 。 


tsconfig.json 支持 文件 通配符 


文件 通配符 来 啦 ! | 支持 文件 通配符 一 直 是 最 需要 的 特性 之 一 。 


类 似 文 件 通 配 符 的 文件 模式 支持 两 个 属性 "include" 和 "exclude" ° 


示例 


"compilerOptions": { 
"module": "commonjs", 
"noImplicitAny": true, 
"removeComments": true, 
"oreserveConstEnums": true, 
YOUR ile: ' HUTA oca lts e TSi 
"sourceMap": true 


3 

"include": [ 
Ug BS ESI 

] 


"exclude": [ 
"node modules", 
nr hosDOD ESY 


支持 文件 通配符 的 符号 有 : 


e * 匹配 零 个 或 多 个 字符 (不 包括 目录 ) 
e ? 匹配 任意 一 个 字符 (不 包括 目录 ) 
e **/ 递归 匹配 所 有 子 目 录 


如 果 文 件 通 配 符 模 式 语句 中 只 包含 * 或 .* ， 那 么 只 匹配 带 有 扩展 名 的 文件 (d 
如 默认 是 .ts ^ .tsx 和 .d.ts ， 如 果 allowJs 设置 
A true > .js 和 ,jsx 也 属于 默认 ) ° 


如 果 "files" 和 "include" 都 没有 指定 ， 编 译 器 默认 包含 所 有 目录 中 的 
TypeScriptx fF ( .ts ^ .d.ts 和 .tsx ) ， 除 了 那些 使 用 exclude 属性 排除 
的 文件 外 。 如 果 allowJs 设置 为 true，JS 文 件 ( .js 和 .jsx ) 也 会 被 包含 进 
Seg 

如 果 "files" 和 "include" 都 指定 了 ， 编 译 器 将 包含 这 两 个 属性 指定 文件 的 并 
集 。 使 用 ourDir 编译 选项 指定 的 目录 文件 总 是 被 排除 ， 即 使 "exclude" 属性 指 
定 的 文件 也 会 被 删除 ， 但 是 files 属性 指定 的 文件 不 会 排除 。 


"exclude" 属性 指定 的 文件 会 对 "include" 属性 指定 的 文件 过 滤 。 但 是 
对 "files" 指定 的 文件 没有 任何 作用 。 当 没有 明确 指定 时 ， "exclude" AHER 


认 会 排除 node modules ^ bower components 和 jspm packages 目录 。 


模块 解析 增加 : BaseUrl ^ X&4£ 8 £4 ` rootDirs te 
追踪 

TypeScript 2.0 提 供 了 一 系列 额外 的 模块 解析 属性 告诉 编译 器 去 哪里 可 以 找到 给 定 模 
块 的 声明 。 


更 多 详情 ， 请 参阅 模块 解析 文档 。 


Base URL 


使 用 了 AMD 模 块 加 载 器 并 且 模 块 在 运行 时 "部署 “ 到 单 文 件 夹 的 应 用 程序 中 使 
用 baseUrl 是 一 种 常用 的 做 法 。 所 有 非 相 对 名 称 的 模块 导入 被 认为 是 相对 
于 baseUrl 的 。 


示例 


{ 
"compilerOptions": { 
"baseUrl": "./modules" 


} 
} 


现在 导入 moduleA 4A ./modules/moduleA 中 查找 。 


import A from "moduleA"; 


路 径 映 射 


有 时 模块 没有 直接 位 于 baseUm 中 。 加 载 器 使 用 映射 配置 在 运行 时 去 映射 模块 名 称 
fe X tt » d & I RequireJs 3: 45 feSystemJS 33 ° 


TypeScript 编 译 器 支持 tsconfig 文件 中 使 用 "paths" 属性 映射 的 声明 。 


示例 


例如 ， 导 入 "jquery" 模块 在 运行 时 会 被 转换 


为 "node modules/jquery/dist/jquery.slim.min.js" ° 


t 
"compilerOptions": { 
"baseUrl": "./node modules", 
Mbacss er 
"jquery": ["jquery/dist/jquery.slim.min"] 
} 
} 
} 


使 用 "paths" 也 允许 更 复杂 的 映射 ， 包 括 多 次 后 退 的 位 置 。 考 虑 一 个 只 有 一 个 地 
方 的 模块 是 可 用 的 ， 其 它 的 模块 都 在 另 一 个 地 方 的 项 目 配置 。 


rootDirs 和 虚拟 目录 


使 用 rootDirs ， 你 可 以 告知 编译 器 的 根 目 录 组 合 这 些 “ 虚 拟 " 目 录 。 因 此 编译 器 在 
这 些 “ 虚 拟 " 目 录 中 解析 相对 导入 模块 ， 仿 佛 是 合并 到 一 个 目录 中 一 样 。 


示例 


给 定 的 项 目 结构 


src 

L— views 
L— viewi.ts (imports './templatei') 
L— view2.ts 


generated 
L— templates 
L— views 
L— templatei.ts (imports './view2') 


构建 步骤 将 复制 /src/views fe /generated/templates/views 目录 下 的 文件 输 
出 到 同一 个 目录 中 。 在 运行 时 ， 视 图 期 望 它 的 模板 和 它 存在 同一 目录 中 ， 因 此 应 该 
使 用 相对 名 称 "./template" 导入 。 

"rootDir" 指定 的 一 组 根 目 录 的 内 容 将 会 在 运行 时 合并 。 因 此 在 我 们 的 例 

子 ， tsconfig.json 文件 应 该 类 似 于 : 


{ 
"compilerOptions": { 
“ootDams aij 
"src/views", 
"generated/templates/views" 
] 
} 
} 
追踪 模块 解析 


--traceResolution 提供 了 一 种 方便 的 方法 ， 以 了 解 模块 如 何 被 编译 器 解析 的 。 


tsc --traceResolution 


快捷 外 部 模块 声明 


当 你 使 用 一 个 新 模块 时 ， 如 果 不 想 要 花费 时 间 书 写 一 个 声明 时 ， 现 在 你 可 以 使 用 快 


捷 声明 以 便 以 快速 开始 。 
declarations.d.ts 


declare module "hot-new-module"; 


所 有 从 快捷 模块 的 导入 都 具有 任意 类 型 。 


import x, {y} from "hot-new-module"; 


x(y); 


模块 名 称 中 的 通配符 


以 前 使 用 模块 加 载 器 (例如 AMD 和 SystemJS) 导入 没有 代码 的 资源 是 不 容易 的 。 
之 前 ， 必 须 为 每 个 资源 定义 一 个 外 部 模块 声明 。 


TypeScript 2.0 支 持 使 用 通配符 符号 ( * ) 定义 一 类 模块 名 称 。 这 种 方式 ， 一 个 声 
明 只 需要 一 次 扩展 名 ， 而 不 再 是 每 一 个 资源 。 


示例 


declare module "*!text" { 
const content: string; 
export default content; 


j 
// Some do it the other way around. 
declare module "json!*" ( 

const value: any; 

export default value; 


现在 你 可 以 导入 匹配 "*i!text" X "json!*" 的 东西 了 。 


import fileContent from "./xyz.txt!text"; 
import data from "json!http://example.com/data.json"; 
console.log(data, fileContent); 


当 从 一 个 基于 非 类 型 化 的 代码 迁移 时 ， 通 配 符 模 块 的 名 称 可 能 更 加 有 用 。 结 合 快捷 
外 部 模块 声明 ， 一 组 模块 可 以 很 容 多 地 声明 为 any 。 


示例 


declare module "myLibrary/*"; 


所 有 位 于 myLibrary 目录 之 下 的 模块 的 导入 都 被 编译 器 认为 是 any 类 型 ， 因 此 
这 些 模块 的 任何 类 型 检查 都 会 被 关闭 。 


import { readFile } from "myLibrary/fileSystem/readFile ; 


readFile(); // readFile 是 'any' 类 型 


支持 UMD 模块 定义 


一 些 库 被 设计 为 可 以 使 用 多 种 模块 加 载 器 或 者 不 是 使 用 模块 加 载 器 (全 局 变量 ) 来 
使 用 ， 这 被 称 为 UMD 或 同 构 模 块 。 这 些 库 可 以 通过 导入 或 全 局 变量 访问 。 


举例 : 
math-lib.d.ts 


export const isPrime(x: number): boolean; 
export as namespace mathLib; 


然后 ， 该 库 可 作为 模块 导入 使 用 : 


import { isPrime } from "math-lib"; 
isPrime(2); 
mathLib.isPrime(2); // 错误 : 无 法 在 模块 内 部 使 用 全 局 定义 


它 也 可 以 被 用 来 作为 一 个 全 局 变量 ， 只 限于 没有 import 和 export 脚本 文件 
中 o 


mathLib.isPrime(2); 


可 选 类 属性 
现在 可 以 在 类 中 声明 可 选 属性 和 方法 ， 与 接口 类 似 。 


示例 


class Bar { 
a: number; 
b?: number; 


f() 1 


[o Ces uel e ale 
} 
g?(): number; // 可 选 方法 的 方法 体 可 以 省 略 
n?() t 


Wet e 


在 --strictNullChecks 模式 下 编译 时 ， 可 选 属性 和 方法 会 自动 添 

加 undefined 到 它们 的 类 型 中 。 因 此 ， 上 面 的 p 属性 类 型 是 number | 
undefined ， 上 面 g 方法 的 类 型 是 (()=> number) | undefined 。 使 用 类 型 保 
护 可 以 去 除 undefined ° 
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类 的 构造 函数 可 以 被 标记 为 private X protected 。 私 有 构造 函数 的 类 不 能 在 
类 的 外 部 实例 化 ， 并 且 也 不 能 被 继承 。 受 保护 构造 函数 的 类 不 能 再 类 的 外 部 实例 
化 ， 但 是 可 以 被 继承 。 


示例 


class Singleton { 
private static instance: Singleton; 


private constructor() { } 
static getInstance() { 


if (!Singleton.instance) { 
Singleton.instance = new Singleton(); 


} 
return Singleton.instance; 
} 
} 
let e = new Singleton(); // 错误 : Singleton 的 构造 函数 是 私有 的 。 
let v = Singleton.getInstance(); 


抽象 属性 和 访问 器 


抽象 类 可 以 声明 抽象 属性 和 、 或 访问 器 。 所 有 子 类 将 需要 声明 抽象 属性 或 者 被 标记 
为 抽象 的 。 抽 象 属性 不 能 初始 化 。 抽 象 访 问 器 不 能 有 具体 代码 块 。 


示例 


abstract class Base { 
abstract name: string; 
abstract get value(); 
abstract set value(v: number); 


} 

class Derived extends Base { 
name = "derived"; 
value = 1; 


隐 式 索引 签名 


如 果 对 象 字面 量 中 所 有 已 知 的 属性 是 赋值 给 索引 签名 ， 那 么 现在 对 象 字 面 量 类 型 可 
以 赋值 给 索引 签名 类 型 。 这 使 得 一 个 使 用 对 象 字 面 量 初始 化 的 变量 作为 参数 传递 给 
期 望 参数 是 map 或 dictionary 的 函数 成 为 可 能 : 


function httpService(path: string, headers: { [x: string]: string 


TRI 


const headers - ( 
"Content-Type": "application/x-www-form-urlencoded" 


iz 


httpService("", ( "Content-Type": "application/x-www-form-urlenc 
oded" 1); // 以 
httpService("", headers); // 现在 可 以 ， 以 前 不 可 以 。 


| 
使 用 --lib 编译 参数 包含 内 置 类 型 声明 


获取 ES6/ES2015 内 置 API 声 明 仅 限于 target: ES6 。 输 入 --lib ， 你 可 以 使 
用 --lib 指定 一 组 项 目 所 需要 的 内 置 APIl。 比 如 说 ， 如 果 你 希望 项 目 运行 时 支 
持 Map ^ Set 和 Promise (例如 现在 静默 更 新 浏览 器 ) ， 直 接 写 --1ib 
es2015.collection,es2015.promise 就 好 了 。 同 样 ， 你 也 可 以 排除 项 目 中 不 需 
要 的 声明 ， 例 如 在 node 项 目 中 使 用 --lib es5,es6 排除 DOM ° 


下 面 是 列 出 了 可 用 的 API : 


e dom 

e webworker 

e esd 

e es6 / es2015 

e es2015.core 

e es2015.collection 
e es2015.iterable 
e es2015.promise 
e es2015.proxy 

e es2015.reflect 

e es2015.generator 


e es2015.symbol 

e es2015.symbol.wellknown 
e es2016 

e es2016.array.include 

e es2017 

e es2017.object 

e es2017.sharedmemory 

e scripthost 


示例 
tsc --target es5 --lib es5,es2015.promise 


"compilerOptions": ( 
"lib": ["es5", "es2015.promise"] 


使 用 --noUnusedParameters 和 -- 
noUnusedLocals 标记 未 使 用 的 声明 


TypeScript 2.0 有 两 个 新 的 编译 参数 来 帮助 你 保持 一 个 干净 的 代码 库 。 - 
noUnusedParameters 编译 参数 标记 所 有 未 使 用 的 函数 或 方法 的 参数 错误 。 -- 
noUnusedLocals 标记 所 有 未 使 用 的 局 部 (未 导出 ) 声明 像 变 量 、 函 数 、 类 和 导入 
等 等 ， 另 外 未 使 用 的 私有 类 成 员 在 --noUnusedLocals 作用 下 也 会 标记 为 错误 。 


示例 


import B, { readFile } from "./b"; 


A Lo9 . ^p^ aay s 4e Boa As H 
/ / ^ 错误 : B 声明 了 ， 但 征 没 有 使 用 。* 


readFile(); 
export function write(message: string, args: string[]) 1 
ey NNNA IR: ‘arg' PUT » 4g 


console.log(message); 


使 用 以 “开头 命名 的 参数 声明 不 会 被 未 使 用 参数 检查 。 例 如 : 


function returnNull(_a) { // 正确 
return null; 


模块 名 称 允许 .js 扩展 名 


TypeScript 2.0 之 前 ， 模 块 名 称 总 是 被 认为 是 没有 扩展 名 的 。 例 如 ， 导 入 一 个 模 
块 import d from "./moduleA.js" ， 则 编译 器 

在 ./moduleA.js.ts 或 ./moduleA.js.d.ts 中 查找 "moduleA.js" 的 定义 。 
这 使 得 像 SystemJS 这 种 期 望 模块 名 称 是 URI 的 打包 或 加 载 工 具 很 难 使 用 。 


使 用 TypeScript 2.0， 编 译 器 将 在 ./moduleA.ts 或 ./moduleA.d.ts 中 查 
找 "moduleA.js" 的 定义 。 


支持 编译 参数 target : es5 和 module: 
es6 同时 使 用 
之 前 编译 参数 target : es5 和 module: ese 同时 使 用 被 认为 是 无 效 的 ， 但 是 现 


在 是 有 效 的 。 这 将 有 助 于 使 用 基于 ES2015 的 tree-shaking (将 无 用 代码 移 除 ) 比如 
rollup ° 
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现在 函数 形 参 和 实 参 列表 末尾 允许 有 去 号 。 这 是 对 第 三 阶段 的 ECMAScript 提 案 的 
实现 , 并 且 会 编译 为 可 用 的 ES3/ES5/ES6 。 


示例 


function foo( 
bar: Bat, 


新 编译 参数 --skipLibCheck 


TypeScript 2.0 添 加 了 一 个 新 的 编译 参数 --skipLibCheck ， 该 参数 可 以 跳 过 声明 
文件 (以 .d.ts 为 扩展 名 的 文件 ) 的 类 型 检查 。 当 一 个 程序 aes 明文 
件 时 ， 编 译 器 需要 花费 大 量 时 间 对 已 知 不 包含 错误 的 声明 进行 类 型 检查 ， 通 过 跳 过 
声明 文件 的 类 型 检查 ， 编 译 时 间 可 能 会 大 大 缩短 。 


由 于 一 个 文件 中 的 声明 可 以 影响 其 他 文件 中 的 类 型 检查 ， 当 指定 -- 
skipLibCheck 时 ， 一 些 错误 可 能 检测 不 到 。 比 如 说 , 如 果 一 个 非 声明 文件 中 的 类 
型 被 声明 文件 用 到 , 可 能 仅 在 声明 文件 被 检查 时 能 发 现 错误 . 不 过 这 种 情况 在 实际 使 
用 中 并 不 常见 


允许 在 声明 中 重复 标识 符 


这 是 重复 定义 错误 的 一 个 常见 来 源 。 多 个 声明 文件 定义 相同 的 接口 成 员 。 


TypeScript 2.02% 35, T 约束 ， 并 允许 可 以 不 同 代码 块 中 出 现 重 复 的 标识 符 , 只 要 
ee. o 


在 同一 代码 块 重复 定义 仍 不 允许 。 


示例 


interface Error { 
stack?: string; 


interface Error { 
code?: string; 
path?: string; 
stack?: string; // OK 


新 编译 参数 --declarationDir 


--declarationDir 可 以 使 生成 的 声明 文件 和 JavaScript 文 件 不 在 同一 个 位 置 中 。 


TypeScript 1.8 
类 型 参数 约束 


在 Tpesenped: 8 F, 类 型 参数 的 限制 可 以 引用 自 同一 个 类 型 参数 列表 中 的 类 型 参 
数 . 在 此 之 前 这 种 做 法 会 报错 . 这 种 特性 通常 被 叫做 F-Bounded Polymorphism. 


| F 


function assign<T extends U, U>(target: T, source: U): T { 
for (let id in source) { 
target[id] = source[id]; 


} 


return target; 


et x- a 31 7b: 2 € 3 dA; 
assign(x, { b: 10, d: 20 }); 
assign(x, (e: 0 }); // 错误 


控制 流 错误 分 析 


TypeScript 1.8 中 引入 了 控制 流 分 析 来 捕获 开发 者 通常 会 遇 到 的 一 些 错误 . 


详情 见 接 下 来 的 内 容 , 可 以 上 手 党 试 


lm 


&TypesScript Virtual Projects ~ | @ bar - 





=] function: foo(x::-boolean):+number: { 
d secifstxi 


4 9 9 »s5 return: 10; 


rm -++-else-f 
te n nn. throw-:new-Error(); 


e return:1; 


} Unreachable code detected 


=|function:bar(x:-number,-y:-boolean):-number: { 
=]++++switch-(x)-{ 

i case-3: -if-(y)-return:-2; 

ETE case:4:-return:3; 

ZIEL default::return:4; 


不 可 及 的 代码 


一 定 无 法 在 运行 时 被 执行 的 语句 现在 会 被 标记 上 代码 不 可 及 错误 . 举 个 例子 , 在 无 条 
件 限制 的 return, throw, break 或 者 continue 后 的 语句 被 认为 是 不 可 及 
的 .使 用 --allowUnreachableCode 来 禁用 不 可 及 代码 的 检测 和 报错 . 


per 
这 里 是 一 个 简单 的 不 可 及 错误 的 例子 : 
RUC ELON TC es 


if (x) 1 


nieturnn enue, 


} 
else { 

return false; 
} 


x20; // 错误 ; 检测 到 不 可 及 的 代码 ， 


这 个 特性 能 捕获 的 一 个 更 常见 的 错误 是 在 return 语句 后 添加 换行 : 


function f() { 


return // 换行 导致 自动 插入 的 分 号 
x: “String, // 错误 : 检测 到 不 可 及 的 代码 ， 


因为 JavaScript 会 自动 在 行 末 结 束 return 语 铭 ,下面 的 对 象 字面 量变 成 了 一 个 
代码 块 . 


未 使 用 的 标签 


未 使 用 的 标签 也 会 被 标记 . 和 不 可 及 代码 检查 一 样 , 被 使 用 的 标签 检查 也 是 默认 开启 
的 .使 用 --allowUnusedLabels 来 禁用 未 使 用 标签 的 报错 . 


fip 


loop: while (x > 0) { // 错误 : 未 使 用 的 标签 . 


X++; 
} 
隐 式 返回 


JS 中 没有 返回 值 的 代码 分 支 会 隐 式 地 返回 undefined . 现在 编译 器 可 以 将 这 种 方 
式 标记 为 隐 式 返回 . 对 于 隐 式 返回 的 检查 默认 是 被 禁用 的 , 可 以 使 用 -- 
noImplicitReturns 来 启用 . 


例子 


function f(x) { // 错误 : 不 是 所 有 分 支 都 返回 了 值 ， 
if (x) { 


return false; 


// 隐 式 返回 7 了 `undefined` 


Case 语句 贯穿 


TypeScript 现在 可 以 在 switch 语 名 中 出 现 贯 穿 的 几 个 非 空 case 时 报错 . 这 个 检测 
默认 是 关闭 的 , 可 以 使 用 --noFallthroughCasesInSwitch 启用 . 


AT 


switch (x % 2) { 
case 0: // 错误 : switch 中 出 现 了 贯穿 的 case， 
console.log("even"); 


case 1: 
console.log("odd"); 
break; 


然而 , 在 下 面 的 例子 中 , 由 于 贯穿 的 case 是 空 的 , 并 不 会 报错 : 


switch (x % 3) { 
case 0: 
case 1: 
console.log("Acceptable"); 
break; 


case 2: 
console.log("This is *two much*!"); 
break; 


React 无 状态 的 部 数组 件 


TypeScript 现在 支持 无 状态 的 函数 组 件 . 它 是 可 以 组 合 其 他 组 件 的 轻 量 级 组 件 . 


// 使 用 参数 解构 和 默认 值 轻松 地 定义 'props' 的 类 型 
const Greeter = ({name = 'world'}) => <div>Hello, {name}!</div>; 


// 参数 可 以 被 检验 
let example = <Greeter name='TypeScript 1.8' />; 


如 果 需 要 使 用 这 一 特性 及 简化 的 props, 请 确认 使 用 的 是 最 新 的 react.d.ts. 


简化 的 React props 类 型 管理 


在 TypeScript 1.8 配合 最 新 的 react.d.ts ( 见 上 方 ) 大 幅 简 化 了 props 的 类 型 声明 . 
具体 的 : 


e 你 不 再 需要 显 式 的 声明 ref 和 key 或 者 extend React.Props 
e ref 和 key 属性 会 在 所 有 组 件 上 拥有 正确 的 类 型 . 
e ref 属性 在 无 状态 函数 组 件 上 会 被 正确 地 禁用. 


模块 中 扩充 全 局 或 者 模块 作用 域 


用 户 现 在 可 以 为 任何 模块 进行 他 们 想 要 , 或 者 其 他 人 已 经 对 其 作出 的 扩充 . 模块 扩充 
的 形式 和 过 去 的 包 模 块 一 致 (例如 declare module "foo" { } 这 样 的 语法 ), 并 
且 可 以 直接 诅 在 你 自己 的 模块 内 , 或 者 在 另外 的 顶级 外 部 包 模 块 中 . 


除 dn TypeScript 还 以 declare global ( ) 的 形式 提供 了 对 于 全 局 声明 的 
扩充 . 这 能 使 模块 对 像 Array 这 样 的 全 局 类 型 在 必要 的 时 候 进 行 扩充 . 


模块 扩充 的 名 称 解 析 规 则 与 import 和 export 声明 中 的 一 致 . 扩充 的 模块 声明 
合并 方式 与 在 同一 个 文件 中 声明 是 相同 的 . 


不 论 是 模块 扩充 还 是 全 局 声明 扩充 都 不 能 向 顶级 作用 域 添加 新 的 项 目 - 它们 只 能 为 
已 经 存在 的 声 AF 添加 "Fh T 


| F 


这 里 的 map.ts 可 以 声明 它 会 在 内 部 修改 在 observable.ts 中 声明 的 
Observable 类 型 ,添加 map 方法 . 


// observable.ts 
export class Observable<T> { 
LE me Tae 


// map.ts 
import { Observable } from "./observable"; 


a aR observables 


declare module "./observable" { 
// 使 用 接口 合并 扩充 'Observable' 类 的 定义 


interface Observable<T> { 
map<U>(proj: (el: T) => U): Observable<U>; 


Observable.prototype.map = /*...*/; 


// consumer.ts 
import { Observable } from "./observable"; 
import "./map"; 


let o: Observable<number>; 
o.map(x -» x.toFixed()); 


相似 的 , 在 模块 中 全 局 作用 域 可 以 使 用 declare global 声明 被 增强 : 


| F 


// 确保 当前 文件 被 当做 一 个 模块 ， 
export {}; 


declare global ( 
interface Array<T> ( 
mapToNumbers(): number[]; 


j 
j 
Array.prototype.mapToNumbers = function () ( /* ... */ } 
字符 囊 字 面 量 类 型 
接受 一 个 特定 字符 串 集 合作 为 某 个 值 的 API 并 不 少见 . 举例 来 说 , 考虑 一 个 可 以 通过 


控制 动画 的 渐变 让 元 素 在 屏幕 中 滑动 的 UL È: 


declare class UlElement { 
animate(options: AnimationOptions): void; 


interface AnimationOptions { 
deltaX: number; 
deltaY: number; 
easing: string; // 可 以 是 "ease-in", "ease-out", "ease-in-out" 





然而 , 这 容易 产生 错误 - 当 用 户 错 误 不 小 心 错 误 拼 写 了 一 个 合法 的 值 时 , 并 没有 任何 


提示 : 


// 没有 报错 
new UIElement().animate(( deltaX: 100, deltaY: 100, easing: "eas 
e-inout" }); 


在 TypeScript 1.8 "P, 我 们 新 增 了 字符 串 字面 量 类 型 . 这 些 类 型 和 字符 串 字 面 量 的 写 
法 一 致 , 只 是 写 在 类 型 的 位 置 . 


用 户 现 在 可 以 确保 类 型 系统 会 捕获 这 样 的 错误 . 这 里 是 我 们 使 用 了 字符 囊 字 面 量 类 
型 的 新 的 Animationoptions : 


interface AnimationOptions { 
deltaX: number; 
deltaY: number; 


easing: "ease-in" | "ease-out" | "ease-in-out"; 
// 错误 : ŽA '"ease-inout"' 不 能 复制 给 类 型 '"ease-in" | "ease-out" 


| "ease-in-out"' 
new UIElement().animate({ deltaX: 100, deltaY: 100, easing: "eas 
e-inout" }); 


更 好 的 联合 /交叉 类 型 接口 
TypeScript 1.8 优化 了 源 类 型 和 目标 类 型 都 是 联合 或 者 交 又 类 型 的 情况 下 的 类 型 准 


+. 举例 来 说 , 当 从 string | string[] 推导 到 string | T HT, 我们 将 类 型 折 
A string[] 和 T ,这 样 就 可 以 将 string[] 推导 为 T. 


| F 


type Maybe<T> = T | void; 
function isDefined<T>(x: Maybe<T>): x is T ( 


return x !== undefined && x !== null; 


function isUndefined<T>(x: Maybe<T>): x is void { 
return x === undefined || x === null; 


function getOrElse<T>(x: Maybe<T>, defaultValue: T): T { 
return isDefined(x) ? x : defaultValue; 


} 
function testi(x: Maybe<string>) { 
let x1 = getOrElse(x, "Undefined" ); // string 
let x2 = isDefined(x) ? x : "Undefined"; MES DICE YGI 
let x3 = isUndefined(x) ? "Undefined" : x; // string 
} 
function test2(x: Maybe<number>) { 
let x1 = getOrElse(x, -1); // number 
let x2 - isDefined(x) ? x : -1; // number 


let x3 = isUndefined(x) ? -1 : x; // number 


使 用 --outFile 合并 AMD 和 System 模块 


在 使 用 --module amd 或 者 --module system 的 同时 制定 --outFile 将 会 
把 所 有 参与 编译 的 模块 合并 为 单个 包括 了 多 个 模块 闭 包 的 输出 文件 . 


每 一 个 模块 都 会 根据 其 相对 于 rootDir 的 位 置 被 计算 出 自己 的 模块 名 称 . 


| F 


L/ SE SV Cia. eS 

import * as B from "./lib/b"; 

export function createA() { 
return B.createB(); 


lf SEC Ibis 
export function createB() { 
return ( Y; 


define("lib/b", ["require", "exports"], function (require, expor 
ts) <f 
"use strict"; 
function createB() { 
return {}; 
} 
exports.createB = createB; 
}); 
define("a", [" require", "exports", "lib/b"], function (require, 
exports, B) 4 
"use strict"; 
function createA() ( 
return B.createB(); 
} 


exports.createA = createA; 


}); 


支持 SystemJS 使 用 default 导入 


像 SystemJS 这 样 的 模块 加 载 器 将 CommonJS 模块 做 了 包装 并 暴露 为 ”default 
ES6 导入 项 . 这 使 得 在 SystemJS 和 CommonJS 的 实现 由 于 不 同 加 载 器 不 同 的 模 
块 导出 方式 不 能 共享 定义 . 


设置 新 的 编译 选项 --allowSyntheticDefaultImports 44 Mp 进行 
导入 的 .ts 或 .d.ts 中 未 指定 的 某 种 类 型 的 默认 导入 项 构建 . 编译 器 会 由 此 推 
断 存在 一 个 default 导出 项 和 整个 模块 自己 一 致 . 


此 选项 在 System 模块 默认 开局 . 
允许 循环 中 被 引用 的 let / const 


之 前 这 样 会 报错 , 现在 由 TypeScript 1.8 支持 . 循环 中 被 函数 引用 的 let / const 
声明 现在 会 被 输出 为 与 let / const 更 新 语义 相符 的 代码 . 


| F 


let list = []; 
for (let 1 — 0; 1 < 5; rtt) f 
list.push(() => i); 


list.forEach(f -» console.log(f())); 


被 编译 为 : 


var last = | |} 
var _loop_1 = function(i) { 
dist. push function O { return 1; 3) 


3 

for (var i = 0; i < 5; i++) { 
_loop_1(i); 

} 


list.forEach(function (f) { return console.log(f()); }); 


然后 结果 是 


WN F © 


改进 的 for..in JEE 


过 去 for..in 变量 的 类 型 被 推断 为 any ， 这 使 得 编译 器 忽略 了 for..in 语句 
内 的 一 些 不 合法 的 使 用 


从 TypeScript 1.8 开始 : 


e 在 for..in 语句 中 的 变量 隐 含 类 型 为 string. 

e 当 一 个 有 数字 索引 签名 对 应 类 型 T (比如 一 个 数组 ) 的 对 象 被 一 个 for..in 
索引 有 数字 索引 签名 并 且 没 有 字符 串 索引 签名 (比如 还 是 数组 ) 的 对 象 的 变量 索 
引 , 产生 的 值 的 类 型 为 T. 


例子 


var a: MyObject[]; 


for (var x ina) { // x I$ 2 X77 string 


var obj = a[x]; // obj 的 类 型 





^] MyObject 


j 


模块 现在 输出 时 会 加 上 "use strict;" 


对 于 ES6 来 说 模块 始终 以 严格 模式 被 解析 , 但 这 一 点 过 去 对 于 非 ES6 目标 在 生成 
的 代码 中 并 没有 遵循 . 从 TypeScript 1.8 开始 , 输出 的 模块 总 会 为 严格 模式 . 由 于 多 
数 严格 模式 下 的 错误 也 是 TS 编译 时 的 错误 , 多 数 代码 并 不 会 有 可 见 的 改动 , 但 是 这 
也 意味 着 有 一 些 东 西 可 能 在 运行 时 没有 征兆 地 失败 , 比如 赋值 给 NaN 现在 会 有 运 
行 时 错误 . 你 可 以 参考 这 篇 MDN 上 的 文章 查看 详细 的 严格 模式 与 非 严格 模式 的 区 
别 列表 . 


使 用 --allowJs 加 入 .js 文件 


经 常 在 项 目 中 会 有 外 部 的 非 TypeScript 编写 的 源 文件 . 一 种 方式 是 将 JS 代码 转换 
为 TS 代码 , 但 这 时 又 希望 将 所 有 JS 代码 和 新 的 TS 代码 的 输出 一 起 打包 为 一 个 文 
fF. 


.js 文件 现在 允许 作为 tsc 的 输入 文件 . TypeScript 编译 器 会 检查 .js MA 
文件 的 语法 错误 , 并 根据 --target 和 --module 选项 输出 对 应 的 代码 . 输出 也 
会 和 其 他 ,ts 文件 一 起 ,js 文件 的 source maps 也 会 像 .ts 文件 一 样 被 生 
JA. 


使 用 --reactNamespace 4 X3 JSX 工厂 


在 使 用 --jsx react 的 同时 使 用 --reactNamespace «JSX 工厂 名 称 > 可 以 允 
许 使 用 一 个 不 同 的 JSX 工厂 代替 默认 的 React. 


新 的 工厂 名 称 会 被 用 来 调用 createElement 和 — spread 方法 . 


QUE 


import {jsxFactory} from "jsxFactory"; 


var div = <div>Hello JSX!</div> 
编译 参数 : 
tsc --jsx react --reactNamespace jsxFactory --m commonJS 


结果 : 


"use strict"; 

var jsxFactory_1 = require("jsxFactory"); 

var div = jsxFactory_1.jsxFactory.createElement("div", null, "He 
Io 48x15 


基于 this HVABKE 
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this is T 现在 是 类 或 接口 方法 的 合法 的 返回 值 类 型 标注 . 当 在 类 型 收 罕 的 位 置 
使 用 时 (比如 if 语句 ), 函数 调用 表达 式 的 目标 对 象 的 类 型 会 被 收 罕 为 T. 


p 


class FileSystemObject { 
isFile(): this is File ( return this instanceof File; ) 
isDirectory(): this is Directory ( return this instanceof Di 
rectory;) 
isNetworked(): this is (Networked & this) { return this.netw 
orked; ) 
constructor(public path: string, private networked: boolean) 
{} 
} 


class File extends FileSystemObject { 
constructor(path: string, public content: string) { super(pa 
th, false); } 
} 
class Directory extends FileSystemObject { 
children: FileSystemObject[]; 
} 
interface Networked { 
host: string; 


let fso: FileSystemObject = new File("foo/bar.txt", "foo"); 
if (fso.isFile()) { 
fso.content; // fso 是 File 


j 


else if (fso.isDirectory()) ( 
fso.children; // fso € Directory 


else if (fso.isNetworked()) { 
fso.host; // fso X networked 


官方 的 TypeScript NuGet & 


从 TypeScript 1.8 开始 , 将 为 TypeScript 编译 器 ( tsc.exe ) 和 MSBuild 整合 
( Microsoft.TypeScript.targets 和 Microsoft.TypeScript.Tasks.dll ) 
提供 官方 的 NuGet &. 


稳定 版 本 可 以 在 这 里 下 载 : 


e Microsoft. TypeScript.Compiler 
e Microsoft. TypeScript. MSBuild 


与 此 同时 , 和 每 日 npm 包 对 应 的 每 日 NuGet 包 可 以 在 https://myget.org 下 载 : 


e TypeScript-Preview 


tsc 错误 信息 更 美观 


我 们 理解 大 量 单 色 的 输出 并 不 直观 . 颜色 可 以 帮助 识别 信息 的 始末 , 这 些 视觉 上 的 线 
索 在 处 理 复杂 的 错误 信息 时 非常 重要 





通过 传递 --pretty 命令 行 选项 , TypeScript 会 给 出 更 丰富 的 输出 , 包含 错误 发 生 
的 上 下 文 . 
号 Windows PowerShell (Admin) = oO x 











ER <1> Windows PowerSh... [ Search AG-yG-~aW= 
PS C:\iFeelPretty> tsc atch tty 


await reticulateSplines(); 





c VS 2015 中 的 JSX 代码 


在 TypeScript 1.8 中 , ISX 标签 现在 可 以 在 Visual Studio 2015 中 被 分 别 和 高 亮 . 


a 





5] TypeScript Virtual Projects -10 
///-<ceference-path="D:\sources\git\react.d.ts"/> 


let -React: -any; 
=|function-render() -{ 
--return-<div-width="5"-className={"some-class-name”" }> 
------some-text-inside 
</div> 


通过 LA -> 选项 -> 环境 -> 字体 与 颜色 ROL VB XML 颜色 和 字体 设置 中 还 
可 以 进一步 改变 字体 和 颜色 来 自 定义 . 


--project ( -p ) 选 项 现在 接受 任意 文件 路 径 


--project 命令 行 选项 过 去 只 接受 包含 了 tsconfig.json 文件 的 文件 夹 . 考虑 
到 不 同 的 构建 场景 , 应 该 允许 --project 指向 任何 兼容 的 ISON x fF. 比如 说 ,一 
个 用 户 可 能 会 希望 为 Node 5 编译 CommonJS 的 ES 2015, 为 浏览 器 编译 AMD 的 
ES5. 现在 少 了 这 项 限制 , 用户 可 以 更 容易 地 直接 使 用 tsc 管理 不 同 的 构建 目标 ， 
无 需 再 通过 一 些 奇 怪 的 方式 , 比如 将 多 个 tsconfig.json 文件 放 在 不 同 的 目录 中 . 


如 果 参 数 是 一 个 路 径 , 行为 保持 不 变 - 编译 器 会 尝试 在 该 目录 下 寻找 名 为 
tsconfig.json 的 文件 . 


允许 tsconfig.json 中 的 注释 


为 配置 添加 文档 是 很 棒 的 ! «tsconfig.json 现在 支持 单行 和 多 行 注 释 . 


"compilerOptions": { 
"target": "ES2015", // 跑 在 node v5 上 ， 
"sourceMap": true // 让 调试 轻松 一 些 


ty 


/* 
/ 


x / 
/ 


"exclude": [ 
"file.d.ts" 


支持 输出 到 IPC 驱动 的 文件 


TypeScript 1.8 允许 用 户 将 --outFile 参数 和 一 些 特殊 的 文件 系统 对 象 一 起 使 用 ， 
比如 命名 的 管道 (pipe), 设备 (devices) =. 
举 个 例子 , 在 很 多 与 Unix 相似 的 系统 上 , 标准 输出 流 可 以 通过 文件 /dev/stdout 
访问 ， 

tsc foo.ts --outFile /dev/stdout 


这 一 特性 也 允许 输出 给 其 他 命令 . 


比如 说 , 我 们 可 以 输出 生成 的 JavaScript 给 一 个 像 pretty-js 这 样 的 格式 美化 工具 : 


tsc foo.ts --outFile /dev/stdout | pretty-js 


改进 了 Visual Studio 2015 中 对 
tsconfig.json 的 支持 
TypeScript 1.8 允许 在 任何 种 类 的 项 目 中 使 用 tsconfig.json 文件 . 包括 


ASP.NET v4 项 目 , 控制 台 应 用 , 以 及 用 TypeScript 开发 的 HTML ÈM. 与 此 同时 ， 
你 可 以 添加 不 止 一 个 tsconfig.json 文件 , 其 中 每 一 个 都 会 作为 项 目的 一 部 分 被 


构建 . 这 使 得 你 可 以 在 不 使 用 多 个 不 同 项 目的 情况 下 为 应 用 的 不 同 部 分 使 用 不 同 的 
配置 . 


fa] Solution 'TypeScriptHTMLApp1' (1 project) 
4 $] TypeScriptHTMLApp1 
b mil References 
4 %& admin 
*TS admin.ts 
+4] tsconfig.json 
*TS users.ts 
4 l app 
+TS app.ts 
+TS home.ts 
+7 tsconfig.json 
+E app.css 
+,[ index.html 
b +42) web.config 


当 项 目 中 添加 了 tsconfig.json 文件 时 , 我 们 还 禁用 了 项 目 属性 页 面 . 也 就 是 说 
所 有 配置 的 改变 必须 在 tsconfig.json 文件 中 进行 . 


一 些 限制 


e 如 果 你 添加 了 一 个 tsconfig.json 文件 , 不 在 其 上 下 文中 的 TypeScript 文件 
不 会 被 编译 . 

e Apache Cordova 应 用 依然 有 单个 tsconfig.json 文件 的 限制 , 而 这 个 文件 
必须 在 根 目 录 或 者 scripts XH. 

e 多 数 项 目 类 型 中 都 没有 tsconfig.json 的 模板 . 


TypeScript 1.7 


支持 async / await 编译 到 ES6 (Node v4+) 


TypeScript 目前 在 已 经 原生 支持 ES6 generator 的 引擎 (比如 Node v4 及 以 上 版 本 ) 
LGD BR. 异步 函数 前 置 async 关键 字 await 会 暂停 执行 , 直到 一 个 异 
步 函 数 执行 后 返回 的 promise 被 fulfill 后 获得 它 的 值 . 


(UT 


在 下 面 的 例子 中 , 输入 的 内 容 将 会 延 时 200 毫秒 逐个 打印 : 
"use strict"; 


// printDelayed 返回 值 是 一 个 'Promise<void>' 
async function printDelayed(elements: string[]) 1 
for (const element of elements) { 
await delay(290); 
console.log(element); 


async function delay(milliseconds: number) { 
return new Promise<void>(resolve => { 
setTimeout(resolve, milliseconds); 


3); 


printDelayed(["Hello", "beautiful", "asynchronous", "world"]).th 
en(() => { 

console.log(); 

console.10g(" 打 印 每 一 个 内 容 !1"); 
3); 


查看 Async Functions 一 文 了 解 更 多 . 


支持 同时 使 用 --target ES6 和 --module 


TypeScript 1.7 将 ES6 添加 到 了 --module 选项 支持 的 选项 的 列表 , 当 编 译 到 
ES6 时 允许 指定 模块 类 型 . 这 让 使 用 具体 运行 时 中 你 需要 的 特性 更 加 灵活 . 


例子 
{ 
"compilerOptions": { 
"module": "amd", 
"target": "ese" 
} 
} 
this 类 型 


在 方法 中 返回 当前 对 象 (也 就 是 this ) 是 一 种 创建 链 式 API 的 常见 方式 . 比如 , 考 
虑 下 面 的 BasicCalculator 模块 : 


export default class BasicCalculator { 
public constructor(protected value: number = 0) { } 


public currentValue(): number { 
return this.value; 


public add(operand: number) ( 
this.value += operand; 
return this; 


public subtract(operand: number) ( 
this.value -- operand; 
return this; 


public multiply(operand: number) ( 
this.value *- operand; 
return this; 


public divide(operand: number) ( 
this.value /- operand; 
return this; 


使 用 者 可 以 这 样 表述 2 * 541: 


import calc from "./BasicCalculator"; 


let v = new calc(2) 
.multiply(5) 
.add(1) 
.currentValue(); 


这 使 得 这 么 一 种 优雅 的 编码 方式 成 为 可 能 ; 然而 , 对 于 想 要 去 继承 
BasicCalculator 的 类 来 说 有 一 个 问题 . 想象 使 用 者 可 能 需要 编写 一 个 


ScientificCalculator : 


import BasicCalculator from "./BasicCalculator"; 


export default class ScientificCalculator extends BasicCalculato 
rt 
public constructor(value - 0) ( 
super(value); 


public square() ( 
this.value - this.value ** 2; 
return this; 


public sin() ( 
this.value - Math.sin(this.value); 
return this; 


因为 BasicCalculator 的 方法 返回 了 this , TypeScript 过 去 推断 的 类 型 是 
BasicCalculator , wÆ ScientificCalculator 的 实例 上 调用 属于 
BasicCalculator 的 方法 , 类 型 系统 不 能 很 好 地 处 理 . 


举例 来 说 : 
import calc from "./ScientificCalculator"; 


let v = new calc(0.5) 
. square() 
.divide(2) 
.sin() // Error: 'BasicCalculator' &# 'sin' Z X. 
.currentValue(); 


这 已 经 不 再 是 问题 - TypeScript 现在 在 类 的 实例 方法 中 , 会 将 this 推断 为 一 个 特 
殊 的 叫做 this 的 类 型 ， this 类 型 也 就 写作 this ,可 以 大 致 理 解 为 "方法 调 
用 时 点 左边 的 类 型 ". 


this 类 型 在 描述 一 些 使 用 了 mixin 风格 继承 的 库 (比如 Ember.js) 的 交叉 类 型 : 


interface MyType { 
extend<T>(other: T): this & T; 
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TypeScript 1.7 支持 将 在 ES7/ES2016 P $ Jo hg 3:5 Lp: ** 和 ** 
算 符 会 被 转换 为 ES3/ES5 中 的 Math.pow . 


举例 


Van ox == 2 oe 


var y = 10; 
y **= 2; 
var z= -(4 ** 3); 


会 生成 下 面 的 JavaScript: 


var x = Math.pow(2, 3); 
var y - 10; 

y - Math.pow(y, 2); 

var z - -(Math.pow(4, 3)); 


改进 对 象 字 面 量 解构 的 检查 
TypeScript 1.7 使 对 象 和 数组 字面 量 解构 初始 值 的 检查 更 加 直观 和 自然 . 
当 一 个 对 象 字面 量 通过 与 之 对 应 的 对 象 解构 绑 定 推断 类 型 时 : 


e 对 象 解构 绑 定 中 有 默认 值 的 属性 对 于 对 象 字 面 量 来 说 可 选 . 


e 对 象 解构 绑 定 中 的 属性 如 果 在 对 象 字 面 量 中 没有 匹配 的 值 , 则 该 属性 必须 有 默 
认 值 , 并 且 会 被 添加 到 对 象 字 面 量 的 类 型 中 . 
e 对 象 字面 量 中 的 属性 必须 在 对 象 解构 绑 定 中 存在 . 


当 一 个 数组 字面 量 通过 与 之 对 应 的 数组 解构 绑 定 推断 类 型 时 : 
e 数组 解构 绑 定 中 的 元 素 如 果 在 数组 字面 量 中 没有 匹配 的 值 , 则 该 元 素 必须 有 默 
认 值 , 并 且 会 被 添加 到 数组 字面 量 的 类 型 中 . 
举例 
// f1 的 类 型 为 (arg?: { x?: number, y?: number }) => void 
FUNCEION: Tick = o yoe na 


// And can be called as: 


f1(); 
f1({}); 

mE x2 1 pe 
fi({ y: 1 }); 


na xe 01 ye L 0) 


// f2 的 类 型 为 (arg?: (x: number, y?: number) => void 
function T2(4 x. y 90 E x: 0 31) 4.3 


f2(); 

TAGE // ik, X 非 可 选 
TAGE xui 5) 

AV L 77 Bie, X Ae 
TACE Xs iy ye i e 


装饰 器 (decorators) 支持 的 编译 目标 版 本 增加 ES3 


装饰 器 现在 可 以 编译 到 ES3. TypeScript 1.7 在 _ decorate R% F#M T ESS 
中 增加 的 reduceRight . 相关 改动 也 内 联 了 对 
Object.getOwnPropertyDescriptor 和 Object.defineProperty 的 调用 , 并 
向 后 兼容 , 使 ES5 的 输出 可 以 消除 前 面 提 到 的 object 方法 的 重复 [ 
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TypeScript 1.6 
JSX 支持 


JSX A — fe THAW RW XML 的 语法 . 它 将 最 终 被 转换 为 合法 的 JavaScript, 124% 
换 的 语义 和 具体 实现 有 关 . ISX 随 着 React 流行 起 来 , 也 出 现在 其 他 应 用 中 . 
TypeScript 1.6 支持 JavaScript 文件 中 JSX MHRA, 类 型 检查 , 以 及 直接 编译 为 
JavaScript 的 选项 . 


新 的 .tsx 文件 扩展 名 和 as 运算 符 
TypeScript 1.6 引入 了 新 的 .tsx 文件 扩展 名 . 这 一 扩展 名 一 方面 允许 TypeScript 
文件 中 的 JSX 语法 , 一 方面 将 as 运算 符 作为 默认 的 类 型 转换 方式 (避免 JSX 表 
达 式 和 TypeScript 前 置 类 型 转换 运算 符 之 间 的 歧义 ). 比如 ; 

var x = «any» foo; 


var x - foo as any; 


使 用 React 


使 用 React 及 JSX 支持 , 你 需要 使 用 React 类 型 声明 . 这 些 类 型 定义 了 ISK 
空间 , 以 便 TypeScript 能 正确 地 检查 React 的 JSX 表达 式 . 比如 : 


> 
N 


/// «reference path="react.d.ts" /> 


interface Props { 
name: string; 


} 


class MyComponent extends React.Component<Props, {}> { 
render() { 
return <span>{this.props.foo}</span> 
} 
} 


«MyComponent name="bar" /»; // 疫 问 题 
«MyComponent name={0} />; // 错误 ，`name ”不 是 一 个 字符 囊 


使 用 其 他 JSX 框架 


JSX 元 素 的 名 称 和 属性 是 根据 ISX 命名 空间 来 检验 的 . 请 查看 JSX 页 面 了 解 如 何 
为 自己 的 框架 定义 JSX 命名 空间 . 


编译 输出 
TypeScript 支持 两 种 JSX 模式 : preserve (保留 ) react. 


e preserve 模式 将 会 在 输出 中 保留 ISX RAN, 使 之 后 的 转换 步骤 可 以 处 理 . 
并 且 输 出 的 文件 扩展 名 为 jsx. 

e react 模式 将 会 生成 React.createElement ,不 再 需要 再 通过 JSX 转换 
即 可 运行 , 输出 的 文件 扩展 名 为 .js . 


查看 JSX 页 面 了 解 更 多 ISX 在 TypeScript 中 的 使 用 . 
交叉 类 型 (intersection types) 
TypeScript 1.6 引入 了 交叉 类 型 作为 联合 类 型 (union types) 逻辑 上 的 补充 . 联合 类 


型 A | B 表示 一 个 类 型 为 A 或 B 的 实体 , 而 交叉 类 型 A&B 表示 一 个 类 
型 同时 为 A 或 B 的 实体 . 


| F 


functzrzon extendsr, B-(first: T, second: MU) P & Uy 
let result = «T & U> {}; 
for (let 1d in first) { 
result[id] = first[id]; 


for (let id in second) { 
if (!result.hasOwnProperty(id)) { 
result[id] = second[id]; 
} 


return result; 


var x = extend({ a: "hello" }, { b: 42 }); 

var S = X.a; 

var n = x.b; 

type LinkedList<T> = T & { next: LinkedList<T> ); 
interface Person { 


name: string; 


var people: LinkedList<Person>; 


var S = people.name; 

var s = people.next.name; 

var s = people.next.next.name; 

var s - people.next.next.next.name; 


interface A ( a: string ) 
interface B ( b: string ) 
interface C { c* string } 


var abc: A&B & C; 


abc.a - "hello"; 
abc.b = "hello"; 
abc.c = "hello"; 


查看 issue #1256 了 解 更 多 . 


本 地 类 型 声明 


本 地 的 类 , 接口 , 枚 举 和 类 型 别名 现在 可 以 在 元 数 声明 中 出 现 . 本 地 类 型 为 块 级 作用 
域 ,与 let 和 const 声明 的 变量 类 似 . 比如 说 : 


function f() { 


if (true) { 
interface T { x: number } 
let v: T; 
Vox = 5; 

} 

else { 
interface T { x: string } 
let v: T; 
v.x = "hello"; 

} 


推导 出 的 函数 返回 值 类 型 可 能 在 函数 内 部 声明 的 . 调用 函数 的 地 方 无 法 引用 到 这 样 
的 本 地 类 型 ,但 是 它 当 然 能 从 类 型 结构 上 匹配 . 比如 : 


interface Point { 
x: number; 
y: number; 


} 
function getPointFactory(x: number, y: number) { 
class P { 
X =x} 
y= Y7 
J 
return P; 


var PointZero - getPointFactory(0, 0); 
var PointOne = getPointFactory(1, 1); 
var p1 = new PointZero(); 
var p2 - new PointZero(); 
var p3 - new PointOne(); 


本 地 的 类 型 可 以 引用 类 型 参数 , 本 地 的 类 和 接口 本 身 即 可 能 是 泛 型 . 比如 : 


PUCELO rE et 
FUNCELON $6 N OE X yi 4 


class C 4 
publie x = x; 
public y = y; 
} 
return es 
} 
let C = f(10, "hello"); 
let v = new C(); 
let x = v.x; // number 
let y=v.y; // string 


WwW 


TypeScript 1.6 增加 了 对 ESO 类 表达 式 的 支持 . 在 一 个 类 表达 式 中 , 类 的 名 称 是 可 选 
的 , 如 果 指明 , 作用 域 仅 限于 类 表达 式 本 身 . 这 和 函数 表达 式 可 选 的 名 称 类 似 . 在 类 表 
达 式 外 无 法 引用 其 实例 类 型 , 但 是 自然 也 能 够 从 类 型 结构 上 匹配 . 比如 ; 


let Point = class { 
constructor(public x: number, public y: number) { } 
public length() { 
return Math-sqrt(thus-x ^ this.x + this-v ^ thiszy); 


var p - new Point(3, 4); // p has anonymous class type 


console.log(p.length()); 


继承 表达 式 


TypeScript 1.6 增加 了 对 类 继承 任意 值 为 一 个 构造 函数 的 表达 式 的 支持 . 这 样 一 来 内 
建 的 类 型 也 可 以 在 类 的 声明 中 被 继承 . 

extends 语句 过 去 需要 指定 一 个 类 型 引用 , 现在 接受 一 个 可 选 类 型 参数 的 表达 式 . 
表达 式 的 类 型 必须 为 有 至 少 一 个 构造 函数 签名 的 构造 函数 , 并 且 需 要 和 extends 
语句 中 类 型 参数 数量 一 致 . 匹配 的 构造 隐 数 签名 的 返回 值 类 型 是 类 实例 类 型 继承 的 
基 类 型 . 如 此 一 来 , 这 使 得 普通 的 类 和 与 类 相似 的 表达 式 可 以 在 extends 语句 中 
使 用 . 


一 些 例子 : 


// 继承 内 建 类 


class MyArray extends Array<number> { } 
class MyError extends Error { } 


// 继承 表达 式 类 
class ThingA { 


getGreeting() { return "Hello from A"; } 


Class ThingB { 
getGreeting() { return "Hello from B"; } 


interface Greeter { 
getGreeting(): string; 


interface GreeterConstructor { 
new (): Greeter; 


function getGreeterBase(): GreeterConstructor { 
return Math.random() >= 0.5 ? ThingA : ThingB; 


class Test extends getGreeterBase() { 
sayHello() { 
console.log(this.getGreeting()); 


abstract (抽象 的 ) 类 和 方法 


TypeScript 1.6 为 类 和 它们 的 方法 增加 了 abstract 关键 字 . 一 个 抽象 类 允许 没有 
被 实现 的 方法 , 并 且 不 能 被 构造 . 


na 


abstract class Base { 
abstract getThing(): string; 
getOtherThing() { return 'hello'; } 


let x = new Base(); // 错误 ，'Base' 是 抽象 的 


// 错误 ， 必须 也 为 抽象 类 ， 或 者 实现 'getThing' 方法 


class Derivedi extends Base { } 


class Derived2 extends Base { 
getThing() { return 'hello'; } 
foo() { 


super.getThing();// 错误 : 不 能 调用 'super' 


var X = new Derived2(); // 正确 

var y: Base = new Derived2(); // 同样 正确 
y.getThing(); // 正确 

y.getOtherThing(); // 正确 


泛 型 别名 


TypeScript 1.6 中 , 类 型 别名 支持 泛 型 . 比如 : 


的 抽象 方法 


type Lazy<T> = T | (() => T); 
var s: Lazy<string>; 

S = eager | 

s = () => "lazy"; 

interface Tuple<A, B> { 


a: A; 
b: B: 


type Pair<T> = Tuple<T, T»; 


更 严格 的 对 象 字 面 量 赋值 检查 
ee uen tL E moa 


查 . 确切 地 说 , 在 将 一 个 新 的 对 象 字 面 量 赋值 给 一 个 变量 , 或 者 传递 给 类 型 非 空 的 参 
数 时 , 如 果 对 象 字面 量 的 属性 在 目标 类 型 中 不 存在 , 则 会 视 为 错误 . 


| F 


Var x: { foo: number }; 
= { foo: 1, baz: 2}; // 错误 ， 多 余 的 属性 “baz 


var : foo: number bar?: number A 
, , 
= foo; 1, baz: 2 ; // 错误 多余 或 者 拼 错 的 属性 ` baz 
{ /7 1 / 


一 个 类 型 可 以 通过 包含 一 个 索引 签名 来 显示 指明 未 出 现在 类 型 中 的 属性 是 被 多 许 的 


var xX: { foo: number, [x2 string]: any y, 
= { foo: 1, baz: 2 }; /7 现在 baz 匹配 了 索引 签名 


ES6 “42 (generators) 


TypeScript 1.6 添加 了 对 于 ES6 输出 的 生成 器 支持 . 


一 个 生成 器 函数 可 以 有 返回 值 类 型 标注 , 就 像 普 通 的 函数 . 标注 表示 生成 器 函数 返回 
的 生成 器 的 类 型 . 这 里 有 个 例子 : 


function *g(): Iterable<string> { 
fOr, (Var Ie 390 c0 T0054) f 
yield ""; // string 可 以 赋值 给 string 


J 
yield * otherStringGenerator(); // otherStringGenerator 必须 
可 遍历 ， 并 且 元 素 类 型 需要 可 赋值 给 string 


} 


没有 标注 类 型 的 生成 器 函数 会 有 自动 推演 的 类 型 . 在 下 面 的 例子 中 , 类 型 会 由 yield 
语句 推演 出 来 : 


unmetonm oe 
Tor (var i= 0; 1 «s 100; 1t4) 4 
yield ""; // 推导 出 string 


} 

yield * otherStringGenerator(); // 推导 出 otherStringGenerato 
r 9 元 素 类 型 
j 


对 async (7-3) 函数 的 试验 性 支持 


TypeScript 1.6 增加 了 编译 到 ES6 时 对 async 函数 试验 性 的 支持 . HH BRAM 
行 一 个 异步 的 操作 , 在 等 待 的 同时 不 会 阻塞 程序 的 正常 运行 . 这 是 通过 与 ESO 兼容 
的 Promise 实现 完成 的 , 并 且 会 将 函数 体 转 换 为 支持 在 等 待 的 异步 操作 完成 时 继 
续 的 形式 . 


由 async 标记 的 函数 或 方法 被 称 作 异 步 函 数 . 这 个 标记 告诉 了 编译 器 该 函数 体 需 
要 被 转换 , 关键 字 await 则 应 该 被 当做 一 个 一 元 re , 而 不 是 标示 符 . T SAEI h 
数 必 须 返 回 类 型 与 Promise 兼容 的 值 . 返回 值 类 型 的 推断 只 能 在 有 一 个 全 局 的 ， 
与 ES6 兼容 的 Promise 类 型 时 使 用 . 


网 下 


TunaSnrrint 1A 
Typescript 1.6 


var p: Promise<number> = /* ... */; 
async function fn(): Promise<number> { 
var i = await p; // 暂停 执行 直到 'p' 得 到 结果 . 'i' 的 类 型 为 "number" 


return 1 + i; 


} 
var a = async (): Promise<number> => 1 + await p; // 暂停 执行 ， 
var a = async () => 1 + await p; // 暂停 执行 ,使 用 --target ES6 3k 


项 编译 时 返回 值 类 型 被 推断 为 "Promise«number»" 


var fe = async function(): Promise<number> { 





var i = await p; // 暂停 执行 知道 'p' 得 到 结果 . 'i' 的 类 型 为 "number" 


return 1 + i; 


} 
Glass Cl 
async m(): Promise<number> { 
var i = await p; // 暂停 执行 知道 'p' 得 到 结果 ,'i' 的 类 型 为 "numb 
er" 
return 1 + i; 
} 
async get p(): Promise<number> { 
var i = await p; // 暂停 执行 知道 'p' 得 到 结果 ,'i' 的 类 型 为 "numb 
er" 
return 1 + i; 
} 
} 


| -A 
每 天 发 布 新 版 本 
由 于 并 不 算 严格 意义 上 的 语言 变化 加 ] 每 天 的 新 版 本 可 以 使 用 如 下 命令 安装 获得 : 


npm install -g typescript@next 


对 模块 解析 逻辑 的 调整 


从 1.6 开始 , TypeScript 编译 器 对 于 "commonjs" 的 模块 解析 会 使 用 一 套 不 同 的 规 
则 . 这 些 规 则 尝试 模仿 Node 查找 模块 的 过 程 . 这 就 意味 着 node 模块 可 以 包含 它 的 
类 型 信息 , 并 且 TypeScript 编译 器 可 以 找到 这 些 信息 . 不 过 用 户 可 以 通过 使 用 -- 
moduleResolution 命令 行 选项 覆盖 模块 解析 规则 . 支持 的 值 有 : 


e ‘classic’ - TypeScript 1.6 以 前 的 编译 器 使 用 的 模块 解析 规则 
e 'node' - 4 node 相似 的 模块 解析 


合并 外 围 类 和 接口 的 声明 
外 围 类 的 实例 类 型 可 以 通过 接口 声明 来 扩展 . 类 构造 函数 对 象 不 会 被 修改 . 比如 说 : 


declare class Foo f 
public x : number; 


interface Foo 1 
V String, 


function bar(foo : Foo) { 
foo.x = 1; // m 22 Foo 中 有 声明 
foo.y = "1"; // RMA, AHA Foo 中 有 声明 


AP XE 3L 85 RAI BR 


TypeScript 1.6 增加 了 一 个 新 的 在 if 语 负 中 收 罕 变 量 类 型 的 方式 , 作为 对 
typeof 和 instanceof 的 补充 . 用 户 定 义 的 类 型 收 窒 函 数 的 返回 值 类 型 标注 形 
HA x is T,3 € x 是 函数 声明 中 的 形 参 ，T 是 任何 类 型 . 当 一 个 用 户 定义 的 
RAI BRE if 语句 中 被 传 入 某 个 变量 执行 时 , 该 变量 的 类 型 会 被 收 罕 到 
ile. 


例子 


functrom iscat(a; any): a is Cat f 
return a.name --- 'kitty'; 


j 


var x: Cat | Dog; 
if(isCat(x)) { 
x.meow(); // AA, x 在 这 个 代码 块 内 是 


} 


tsconfig.json 对 exclude 属性 的 支持 


一 个 没有 写 明 files 属性 的 tsconfig.json 文件 (默认 会 引用 所 有 子 目 录 下 
的 *.ts 文件 ) 现在 可 以 包含 一 个 exclude 属性 , 指定 需要 在 编译 中 排除 的 文件 或 
者 目录 列表 .exclude 属性 必须 是 一 个 字符 串 数 组 , 其 中 每 一 个 元 素 指 定 对 应 的 一 
个 文件 或 者 文件 夹 名 称 对 于 tsconfig.json 文件 所 在 位 置 的 相对 路 径 . 举例 来 说 : 


{ 
"compilerOptions": f 
"out: WESSE a JSS 
tr 
"exclude": [ 
"node_modules", 
Utestebs'. 
MUMS NDS 
] 
} 


exclude 列表 不 支持 通配符 . 仅仅 可 以 是 文件 或 者 目录 的 列表 . 


- -init 命令 行 选项 


在 一 个 目录 中 执行 tsc --init 可 以 在 该 目录 中 创建 一 个 包含 了 默认 值 的 
tsconfig.json . 可 以 通过 一 并 传递 其 他 选项 来 生成 初始 的 tsconfig.json . 


TypeScript 1.6 
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TypeScript 1.5 


ES6 模块 


TypeScript 1.5 支持 ECMAScript 6 (ES6) 模块 . ES6 模块 可 以 看 做 之 前 TypeScript 

的 外 部 模块 换 上 了 新 的 语法 : ES6 模块 是 分 开 加 载 的 源 文件 , 这 些 文件 还 可 能 引入 其 

他 模块 , 并 且 导 出 部 分 供 外 部 可 访问 . ESO 模块 新 增 了 几 种 导入 和 导出 声明 . 我 们 建 

议 使 用 TypeScript 开发 的 库 和 应 用 能 够 更 新 到 新 的 语法 , 但 不 做 强制 要 求 . 新 的 

ES6 模块 语法 和 TypeScript 原来 的 内 部 和 外 部 模块 结构 同时 被 支持 , 如 果 需 要 也 可 
ZA EG [zi 合 使 用 . 


导出 声明 


作为 TypeScript 已 有 的 export 前 级 支持 , 模块 成 员 也 可 以 使 用 单独 导出 的 声明 
导出 , 如 果 需 要 ，as 语句 可 以 指定 不 同 的 导出 名 称 . 


interface Stream n p 
function writeToStr ne Stream, data: string) m m 
export { Stream, writeToStream as write ); // writeToStream 号 出 


J write 


引入 声明 也 可 以 使 用 as 语句 来 指定 一 个 不 同 的 导入 名 称 . 比如 : 


import { read, write, standardOutput as stdout } from "./inout"; 
var s = read(stdout); 
write(stdout, s); 


作为 单独 导入 的 候选 项 , 命名 空间 导入 可 以 导入 整个 模块 : 


import * as io from "./inout"; 
var s = io.read(io.standardOutput); 
io.write(io.standardOutput, s); 


重新 导出 


使 用 from 语句 一 个 模块 可 以 复制 指 
名 称 . 


定 模块 的 导出 项 到 当前 模块 , 而 无 需 创建 本 地 


export { read, write, standardOutput as stdout } from "./inout"; 


export * 可 以 用 来 重新 导出 另 一 个 模块 的 所 有 导出 项 . 在 创建 一 个 聚合 了 其 他 几 


个 模块 导出 项 的 模块 时 很 方便 . 


export function transform(s: string): string { ... } 


export * from "modd 
export * from "./mod2"; 


默认 导出 项 


一 个 export default 声明 表示 一 个 表达 式 是 这 个 模块 的 默认 导出 项 . 


export default class Greeter { 


sayHello() { 
console.log("Greetings!"); 


对 应 的 可 以 使 用 默认 导入 : 
import Greeter from "./greeter"; 


var g = new Greeter(); 
g.sayHello(); 


无 导入 加 载 


"无 导入 加 载 " 可 以 被 用 来 加 载 菜 些 只 需要 其 副作用 的 模块 . 


dmpobto -./ POLY mS 
了 解 更 多 关于 模块 的 信息 , 请 参见 ES6 模块 支持 规范 . 


声明 与 赋值 的 解构 
TypeScript 1.5 添加 了 对 ES6 解构 声明 与 赋值 的 支持 . 


解构 


解构 声明 会 引入 一 个 或 多 个 命名 变量 , 并 且 初 始 化 它们 的 值 为 对 象 的 属性 或 者 数组 
的 元 素 对 应 的 值 . 


比如 说 ,下 面 的 例子 声明 了 变量 x, y fe z ,并 且 分 别 将 它们 的 值 初始 化 为 
getSomeObject().x , getSomeObject().y 和 getSomeObject().z : 


var { x, y, Zz } = getSomeObject(); 
解构 声明 也 可 以 用 于 从 数组 中 得 到 值 . 
var [x, y, Z = 10] = getSomeArray(); 


相似 的 , 解构 可 以 用 在 函数 的 参数 声明 中 : 


function drawText({ text = "", location: [x, y] = [0, 0], bold = 
false }) { 
// ARXA 


// 以 一 个 对 象 字面 量 为 参数 调用 drawText 
var item = { text: "someText", location: [1,2,3], style: "italic 
5" ys 


drawText(item); 


赋值 


解构 也 可 以 被 用 于 普通 的 赋值 表达 式 . 举例 来 讲 , 交换 两 个 变量 的 值 可 以 被 写作 一 个 
解构 赋值 : 


var x = 1; 
var y - 2; 
[x, y] = Ly, x]; 


namespace (4.2 È lal) 关键 字 
过 去 TypeScript 中 module 关键 字 既 可 以 定义 "内 部 模块 " 也 可 以 定义 "外 部 模 


块 "; 这 让 刚刚 接触 TypeScript MA AAA HA A. "内 部 模块 " 的 概念 更 接近 于 大 部 
分 人 眼中 的 命名 空间 ; 而 "外 部 模块 " 对 于 JS 来 讲 , 现在 也 就 是 模块 了 . 


主意 : 之 前 定义 内 部 模块 的 语法 依然 被 支持 . 


之 前 : 


module Math { 
export function add(x, y) { ... } 


} 
之 后 : 


namespace Math { 
export function add(x, y) { ... } 


} 


let 和 const 的 支持 


ES6 的 let 和 const 声明 现在 支持 编译 到 ES3 和 ESS. 


Const 


const MAX = 100; 


/ `c Ax SU EUER o- 265 qnm- A SP €. 
+4MAX; // 错误 : BJÉ/GUGERDAMOR8EDCT ANR E 


块 级 作用 域 


if (true) T 
let a = 4 


else { 
let a = "string"; 


alert(a); // 错误 : 变量 a 在 当前 作用 域 未 定义 


for...of 的 支持 


TypeScript 1.5 增加 了 ES6 for...of 循环 编译 到 ES3/ES5 时 对 数组 的 支持 , 以 


及 编译 到 ES6 时 对 满足 Iterator 接口 的 全 面 支持 . 


例子 


TypeScript 编译 器 会 转译 for...of 数组 到 具有 语义 的 ES3/ES5 JavaScript (如 


果 被 设置 为 编译 到 这 些 版 本 ). 


for (var v of expr) { } 


» 
a 
i 
x 


for (var i = 0, a = expr; _i < a.length; _i++) { 
var v = a[ i]; 


e 一 个 表达 式 

e 并 且 值 为 一 个 函数 

e 接受 target, name ， 以 及 属性 描述 对 象 作为 参数 
e 可 选 返回 一 个 会 被 应 用 到 目标 对 象 的 属性 描述 对 象 


| F 


装饰 器 readonly 和 enumerable(false) 会 在 属性 method 添加 到 类 c 
上 之 前 被 应 用 . 这 使 得 装饰 器 可 以 修改 其 实现 , 具体 到 这 个 例子 , 设置 了 


descriptor 为 writable: false 以 及 enumerable: false 


Glass C { 
@readonly 
@enumerable( false) 
method() { } 


function readonly(target, key, descriptor) { 
descriptor.writable = false; 


function enumerable(value) { 
return function (target, key, descriptor) { 
descriptor.enumerable = value; 


计算 属性 


使 用 动态 的 属性 初始 化 一 个 对 象 可 能 会 很 矿 烦 . 参考 下 面 的 例子 : 


type NeighborMap = { [name: string]: Node }; 
type Node = { name: string; neighbors: NeighborMap; } 


function makeNode(name: string, initialNeighbor: Node): Node { 
var neighbors: NeighborMap = {}; 
neighbors[initialNeighbor.name] = initialNeighbor; 
return ( name: name, neighbors: neighbors }; 


这 里 我 们 需要 创建 一 个 包含 了 neighbor-map 的 变量 , 便于 我 们 初始 化 它 . 使 用 
TypeScript 1.5, 我 们 可 以 让 编译 器 来 干 重活 : 


function makeNode(name: string, initialNeighbor: Node): Node { 
return { 
name: name, 
neighbors: { 
[initialNeighbor.name]: initialNeighbor 


指出 UMD 和 System 模块 输出 


作为 AMD 和 CommonJS 模块 加 载 器 的 补充 , TypeScript 现在 支持 输出 为 UMD 
(Universal Module Definition) 和 System 模块 的 格式 . 


用 法 : 
tsc --module umd 
以 及 


tsc --module system 


Unicode 字符 串 码 位 转 义 


ES6 中 允许 用 户 使 用 单个 转 义 表示 一 个 Unicode 码 位 . 


举 个 例子 , 考虑 我 们 需要 转 义 一 个 包含 了 字符 " 的 字符 串 . UTF-16/USC2 v," 
被 表示 为 一 个 代理 对 , 意思 就 是 它 被 编码 为 一 对 16 位 值 的 代码 单元 , 具体 来 说 是 

OxD842 和 OXDFB7 .之 前 这 意味 着 你 必须 将 该 码 位 转 义 为 "\uD842\UuDFB7" . 
这 样 做 有 一 个 重要 的 问题 , 就 事 很 难 讲 两 个 独立 的 字符 同一 个 代理 对 区 分 开 来 . 


通过 ESG 的 码 位 转 义 , 你 可 以 在 字符 串 或 模板 字符 串 中 清晰 地 通过 一 个 转 义 表示 一 
个 确切 的 字符 : "Nu(20bb7)" . TypeScript 在 编译 到 ES3/ES5 时 会 将 该 字符 串 输 
出 为 "\uD842\uDFB7" . 


标签 模板 字符 串 编 译 到 ES3/ES5 


TypeScript 1.4 "P, 我 们 添加 了 模板 字符 串 编译 到 所 有 ES 版 本 的 支持 , 并 且 支 持 标 
签 模板 字符 串 编译 到 ES6. 得 益 于 @ivogabe 的 大 量 付出 , 我 们 填补 了 标签 模板 字符 
串 对 编译 到 ES3/ES5 的 支持 . 


当 编 译 到 ES3/ES5 时 , 下 面 的 代码 ; 


function oddRawStrings(strs: TemplateStringsArray, n1, n2) { 
return strs.raw.filter((raw, index) => index % 2 === 1); 


oddRawStrings "Hello \n${123} Nt ${456}\n world' 
会 被 输出 为 : 


function oddRawStrings(strs, ni, n2) { 

return strs.raw.filter(function (raw, index) { 

return index 96 2 === 1; 

3); 
} 
(a = ["Hello Xn", " Nt ") "Xn world", _a.raw = ["Hello xxn". " 
\At ", "\\n world"], oddRawStrings(_a, 123, 456)); 
var _a; 


AMD 可 选 依赖 名 称 


/// <amd-dependency path="x" /> 会 告诉 编译 器 需要 被 注入 到 模块 
require 方法 中 的 非 TS 模块 依赖 ; 然而 在 TS 代码 中 无 法 使 用 这 个 模块 . 


新 的 amd-dependency name 属性 允许 为 AMD 依赖 传递 一 个 可 选 的 名 称 . 


/// «amd-dependency path="legacy/moduleA" name="moduleA"/> 
declare var moduleA:MyType 
moduleA.callStuff() 


生成 的 JS 代码 : 


define(["require", "exports", "legacy/moduleA"], function (requi 
re, exports, moduleA) ( 
moduleA.callStuff() 


3); 


通过 tsconfig.json 指示 一 个 项 目 


通过 添加 tsconfig.json 到 一 个 目录 指明 这 是 一 个 TypeScript 项 目的 根 目录 . 
tsconfig.json 文件 指定 了 根 文 件 以 及 编译 项 目 需要 的 编译 器 选项 . 一 个 项 目 可 
以 由 以 下 方式 编译 : 


e 调用 tsc 并 不 指定 输入 文件 , 此 时 编译 器 会 从 当前 目录 开始 往 上 级 目录 寻找 
tsconfig.json 文件 . 

e 调用 tsc 并 不 指定 输入 文件 ,使 用 -project (或 者 -p ) 命 令 行 选 项 指定 包 
& 1 tsconfig.json 文件 的 目录 . 


例子 


"compilerOptions": { 
"module": "commonjs", 
"noImplicitAny": true, 
"sourceMap": true, 


| 


参见 tsconfig.json wiki 页 面 查看 更 多 信息 . 


qu 


--rootDir 命令 行 选 项 
选项 --outDir 在 输出 中 会 保留 输入 的 层级 关系 . 编译 器 将 所 有 输入 文件 共有 的 
最 长 路 径 作为 根 路 径 : 并 且 在 输出 中 应 用 对 应 的 子 层 级 关系 . 


有 的 时 候 这 并 不 是 期 望 的 结果 , 比如 输入 FolderA\FolderB\1.ts 和 
FolderA\FolderB\2.ts ,输出 结构 会 是 FolderA\FolderB\、 对 应 的 结构 . 如 果 
a AP #28 FolderA\3.ts 文件 , 输出 的 结构 将 突然 变 为 FolderA\、 对 应 的 结 
H. 


--rootDir 指定 了 会 输出 对 应 结构 的 输入 目录 , 不 再 通过 计 草 获得 . 


- -noEmitHelpers 命令 行 选项 


TypeScript 编译 器 在 需要 的 时 候 会 输出 一 些 像 ”extends 这 样 的 工具 函数 . 这 些 
函数 会 在 使 用 它们 的 所 有 文件 中 输出 . 如 果 你 想 要 聚合 所 有 的 工具 函数 到 同一 个 位 
B, 或 者 覆盖 默认 的 行为 , 使 用 --noEmitHelpers 来 告知 编译 器 不 要 输出 它们 . 


--newLine 命令 行 选项 


默认 输出 的 换行 符 在 Windows 上 是 \r\n ,在 *nix 上 是 \n . --newLine 命令 
行 标记 可 以 履 盖 这 个 行为 , 并 指定 输出 文件 中 使 用 的 换行 符 . 


--inlineSourceMap and inlineSources 
命令 行 选 项 


--inlineSourceMap J AIR CHR] .js 文件 , 而 不 是 在 单独 的 
.js.map 文件 中 . --inlinesources 允许 进一步 将 .ts 文件 内 容 包 含 到 输出 
文件 中 . 
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概述 


联合 类 型 有 助 于 表示 一 个 值 的 类 型 可 以 是 多 种 类 型 之 一 的 情况 。 比 如 ， 有 一 个 API 
接 命令 行 传 入 string 类 型 ， string[] 类 型 或 者 是 一 个 返回 string 的 函数 。 
你 就 可 以 这 样 写 : 


interface RunOptions { 
program: string; 
commandline: string[]|string|(() => string); 


} 
给 联合 类 型 赋值 也 很 直观 -- 只 要 这 个 值 能 满足 联合 类 型 中 任意 一 个 类 型 那么 就 可 以 
赋值 给 这 个 联合 类 型 

var opts: RunOptions = /* ... */; 

opts.commandline = '-hello world'; // OK 


opts.commandline = ['-hello', 'world']; // OK 
opts.commandline = [42]; // Error， 数 字 不 是 字符 串 或 字符 串 数 组 


当 读 取 联合 类 型 时 ， 你 可 以 访问 类 型 共有 的 属性 : 


if(opts.length === 0) { // 0K，string 和 string[] 都 有 'length' 属 性 
console.log("it's empty"); 


使 用 类 型 保护 ， 你 可 以 轻松 地 使 用 联合 类 型 : 
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function formatCommandline(c: string|string[]) { 


if(typeof c === 'string') { 
return c.trim(); 
) else { 


return ¢. joint" 1); 


严格 的 泛 型 


随 着 联合 类 型 可 以 表示 有 很 多 类 型 的 场景 ， 我 们 决定 去 改进 泛 型 调用 的 规范 性 。 之 
前 ， 这 段 代码 编译 不 会 报错 (出 乎 意料 ) 


function equal<T>(1lhs: T, rhs: T): boolean { 
return lhs --- rhs; 


// 之 前 没有 错误 
// 现在 会 报错 :在 String 和 number 之 前 没有 最 佳 的 基本 类 型 
var e = equal(42, 'hello'); 


通过 联合 类 型 ， 你 可 以 指定 你 想 要 的 行为 ， 在 函数 定义 时 或 在 调用 的 时 候 : 


// 'choose' function where types must match 

function choosei<T>(a: T, b: T): T { return Math.random() > 0.5 
Pa bo 

var a = choosed('hello', 42); // Error 

var b = choosei<string|number>('hello', 42); // OK 


// 'choose' function where types need not match 

function choose2<T, U>(a: T, b: U): T[U { return Math.random() > 
prb ca p 

var c = choose2('bar', 'foo'); // OK, c: string 

var d = choose2('hello', 42); // OK, d: string |number 


ee mil 
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更 好 的 类 型 推断 


当 一 个 集合 里 有 多 种 类 型 的 值 时 ， 联 合 类 型 会 为 数组 或 其 它 地 方 提供 更 好 的 类 型 推 
BT: 


var x = [1, 'hello']; // x: Array<string|number> 
x[0] = 'world'; // OK 
x[0] = false; // Error, boolean is not string or number 


let 声明 


di JavaScriptZ > var 声明 会 被 "提升 ?到 所 在 作用 域 的 顶端 。 这 可 能 会 引发 一 些 让 
人 不 解 的 bugs : 


console.log(x); // meant to write 'y' here 
/* later in the same block */ 


var x - 'hello'; 


TypeScript 已 经 支持 新 的 ES6 的 关键 字 let ， 上 声明 一 个 块 级 作用 域 的 变量 。 一 
个 let 变量 只 能 在 声明 之 后 的 位 置 被 引用 ， 并 且 作 用 域 为 声明 它 的 块 里 : 


If(foo) { 

console.log(x); // Error, cannot refer to x before its decla 
ration 

let x = 'hello'; 
} else { 


console.log(x); // Error, x is not declared in this block 


let 只 在 设置 目标 为 ECMAScript6 ( --target ES6 ) 时 生效 。 


const 声明 


另 一 个 TypeScript 支 持 的 ES6 里 新 出 现 的 声明 类 型 是 const 。 不 能 给 一 
个 const 类 型 变量 赋值 ， 只 能 在 声明 的 时 候 初 始 化 。 这 对 于 那些 在 初始 化 之 后 就 
不 想 去 改变 它 的 值 的 情况 下 是 很 有 帮助 的 : 


const halfPi = Math.PI / 2; 


halfPi = 2; // Error, can't assign to a 'const' 


const 只 在 设置 目标 为 ECMAScript6 ( --target ES6 ) 时 生效 。 


让 >> 人 大 
模版 字符 串 
TypeScript 现 已 支持 ES6 模 块 字 符 串 。 通 过 它 可 以 方便 地 在 字符 囊 中 嵌入 任何 表达 
A: 
var name - "TypeScript"; 
var greeting = “Hello, ${name}! Your name has ${name.length} ch 


aracters ; 


当 编 译 目 标 为 ES6 之 前 的 版 本 时 ， 这 个 字符 串 被 分 解 为 : 


var name = "TypeScript!"; 


var greeting = "Hello, " + name + "! Your name has " + name.leng 
th + " characters"; 


类 型 守护 


JavaScript 常 用 模式 之 一 是 在 运行 时 使 用 typeof 或 instanceof 检查 表达 式 的 类 
Aloo fe if 语句 里 使 用 它们 的 时 候 ，TypeScript 可 以 识别 出 这 些 条 件 并 且 随 之 改变 
类 型 推断 的 结果 。 


使 用 typeof 来 检查 一 个 变量 : 


van Xx any = v ate 2G 
if(typeof x === 'string') { 


console.log(x.subtr(1)); // Error, 'subtr' 


ss CRUDO 
j 
// X is still any here 
x.unknown(); // OK 


结合 联合 类 型 使 用 typeof 和 else 


var x: string|HTMLElement = /* ... */; 
if(typeof x === 'string') { 

// x is string here, as shown above 
) else f 

// x is HTMLElement here 

console.log(x.innerHTML); 


结合 类 和 联合 类 型 使 用 instanceof 


class Dog ( woof() { } } 
class Cat { meow() { } } 


var pet: Dog|Cat = /* ... */; 
if(pet instanceof Dog) { 
pet.woof(); // OK 
) else { 
pet.woof(); // Error 


类 型 别名 


你 现在 可 以 使 用 type 关键 字 来 为 类 型 定义 一 个 “别名 ”: 


does not exist on 


type PrimitiveArray = Array<string|number boolean»; 
type MyNumber = number; 

type NgScope = ng.IScope; 

type Callback = () => void; 


类 型 别名 与 其 原始 的 类 型 完全 一 致 ; 它们 只 是 简单 的 替代 名 。 


const enum (X A SE ALAS TU ) 
枚 举 很 有 帮助 ， 但 是 有 些 程 序 实 际 上 并 不 需要 它 生 成 的 代码 并 且 想 要 将 枚 举 变 量 所 
代码 的 数字 值 直 接替 换 到 对 应 位 置 上 。 新 的 const enum 声明 与 正常 的 enum 在 
类 型 安全 方面 具有 同样 的 作用 ， 只 是 在 编译 时 会 清除 掉 。 


const enum Suit { Clubs, Diamonds, Hearts, Spades } 
var d = Suit.Diamonds; 


Compiles to exactly: 


var d= 1; 


TypeScript 也 会 在 可 能 的 情况 下 计算 枚 举 值 : 


enum MyFlags { 


None = 0, 
Neat = i, 
Cool = 2, 


Awesome = 4, 
Best = Neat | Cool | Awesome 


} 


var b = MyFlags.Best; // emits var b = 7; 


-noEmitOnError 命令 行 选项 


TypeScript 编 译 器 的 默认 行为 是 当 存 在 类 型 错误 〈 比 如 ， 将 string 类 型 赋值 

给 number 类 型 ) 时 仍 会 生成 .js 文件 。 这 在 构建 服务 器 上 或 是 其 它 场景 里 可 能 会 是 
不 想 看 到 的 情况 ， 因 为 希望 得 到 的 是 一 次 “纯净 "的 构建 。 新 的 noEmitonError 标 
记 可 以 阻止 在 编译 时 遇 到 错误 的 情况 下 继续 生成 .js 代码 。 


它 现 在 是 MSBuild 工 程 的 默认 行为 ;这 允许 MSBuild 持 续 构 建 以 我 们 想 要 的 行为 进 
行 ， 输 出 永远 是 来 自 纯净 的 构建 。 


AMD 模块 名 


默认 情况 下 AMD 模 块 以 匿名 形式 生成 。 这 在 使 用 其 它 工具 (比如 ，r.js) 处 理 生成 
By 1 IR AY AY T AES OR CURL o 


新 的 amd-module name 标签 允许 给 编译 器 传 入 一 个 可 选 的 模块 名 : 


//// [amdModule.ts] 
///«amd-module name='NamedModule' /> 
export class C ( 


j 


结果 会 把 NamedModule 赋值 成 模块 名 ， 做 为 调用 AMD define 的 一 部 分 : 


//// [amdModule. js] 
define("NamedModule", ["require", "exports"], function (require, 
exports) { 
var C = (function () { 
function C() { 
} 
[exe (rim (65 
3)0; 
exports.C - C; 


I) 
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A TRAP HY 


X € d 318] protected 修饰 符 作 用 与 其 它 语言 如 C++，C# 和 Java 中 的 一 样 。 一 个 
类 的 protected 成 员 只 在 这 个 类 的 子 类 中 可 见 


class Thing { 
protected doSomething() { /* ... */ } 


class MyThing extends Thing { 
public myMethod() { 
// 0K， 可 以 在 子 类 里 访问 受 保 护 的 成 员 
this.doSomething(); 


j 
var t = new MyThing(); 
t.doSomething(); // Error， 不 能 在 类 外 部 访问 受 保护 成 员 


元 组 类 型 


元 组 类 型 表示 一 个 数组 ， 其 中 元 素 的 类 型 都 是 已 知 的 ， 但 是 不 一 样 是 同样 的 类 型 。 
比如 ， 你 可 能 想 要 表示 一 个 第 一 个 元 素 是 string 类 型 第 二 个 元 素 是 number X 
型 的 数组 : 


// Declare a tuple type 
var x: [string, number]; 
// 初始 化 
x = [’hello', 10]; OK 
// 错误 的 初始 化 
= [10, *hello*]; 7/ Error 


但 是 访问 一 个 已 知 的 索引 ， 会 得 到 正确 的 类 型 : 
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console.log(x[0].substr(1)); // OK 
console.log(x[1].substr(1)); // Error, 'number'&%'substr' 7x 


注意 在 TypeScript1.4 里 ， 当 访问 超出 已 知 索引 的 元 素 时 ， 会 返回 联合 类 型 : 


x[3] = 'world'; // OK 

console.log(x[5].toString()); // OK, 'string'#*'number' #84 tostri 
ng 

x[6] = true; // Error, boolean# number Xstring 
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改进 性 能 


az 


1.1 版 本 的 编译 器 速度 比 所 有 之 前 发 布 的 版 本 快 4 倍 。 阅 读 这 篇 博客 里 的 有 关 图 表 


更 好 的 模块 可 见 性 规则 


TypeScript 现 在 只 在 使 用 --declaration 标记 时 才 严 格 强制 模块 里 类 型 的 可 见 
性 。 这 在 Angular 里 很 有 用 ， 例 如 : 


module MyControllers { 
interface ZooScope extends ng.IScope { 
animals: Animal[]; 
} 
export class ZooController { 
// Used to be an error (cannot expose ZooScope), but now is 
only 
// an error when trying to generate .d.ts files 
constructor (public $scope: ZooScope) { } 
/* more code */ 


preaking UNaNnGes 


Breaking Changes 


e TypeScript 2.3 
e TypeScript 2.2 
e TypeScript 2.1 
e TypeScript 2.0 
e TypeScript 1.8 
e TypeScript 1.7 
e TypeScript 1.6 
e TypeScript 1.5 
e TypeScript 1.4 
e TypeScript 1.1 


DeoCrIpt 2.9 
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TypeScript 2.3 


完整 的 破坏 性 改动 列表 请 到 这 里 查看 :breaking change issues. 


空 的 泛 型 列表 会 被 标记 为 错误 


class X<> {} // Error: Type parameter list cannot be empty. 
function f<>() {} // Error: Type parameter list cannot be empty. 


const x: X<> = new X<>(); 
be empty. 


// Error: Type parameter list cannot 


sd 


TypeScript 2.2 


完整 的 破坏 性 改动 列表 请 到 这 里 查看 :breaking change issues. 


标准 库 里 的 DOM API 变 动 


e 现在 标准 库 里 有 Window.fetch 的 声明 ; 仍 依赖 于 QtypesNwhatwg- 
fetch 会 产生 声明 冲突 错误 ， 需 要 被 移 除 。 

e 现在 标准 库 里 有 Serviceworker 的 声明 ; 仍 依赖 
于 @types\service_worker_api 会 产生 声明 冲突 错误 ， 需 要 被 移 除 。 


TypeScript 2.1 


完整 的 破坏 性 改动 列表 请 到 这 里 查看 :breaking change issues. 


生成 的 构造 函数 代码 将 this 的 值 替换 
为 super(...) 调用 的 返回 值 
在 ES2015 中 ， 如 果 构 造 通 数 返回 一 个 对 象 ， 那 么 对 于 任何 super(...) 的 调用 者 


将 隐 式 地 替换 掉 this 的 值 。 因 此 ， 有 必要 获取 任何 可 能 的 super(...) 的 返回 
值 并 用 this 进行 替换 。 


示例 
定义 一 个 类 C : 
class C extends B ( 


public a: number; 
constructor() { 


super(); 
this.a = 0; 
} 
} 
将 生成 如 下 代码 : 


var C = (function (_super) { 
. extends(C, super); 
function €() f 


var this = super.call(this) || this; 
_this.a = 0; 
return _this; 

} 

ise Cr 


3(B)); 


VERE ， 


e  super.call(this) 存 入 局 部 变量 this 

e HERREMA this 的 地 方 都 被 替换 为 super 调用 的 返回 值 ( 例 
如 this ) 

e 每 个 构造 函数 将 明确 地 返回 它 的 this ， 以 确保 正确 的 继承 


值得 注意 的 是 在 super(...) 调用 前 就 使 用 this 从 TypeScript 1.8 开 始 将 会 引发 


错误 。 


继承 内 置 类 型 如 Error > Array 和 Map 将 是 
无 效 的 


做 为 将 this 的 值 替换 为 super(...) 调用 返回 值 的 一 部 分 ， 子 类 

化 Error ， Array ¥ 492 5 果 可 以 是 非 预料 的 。 这 是 因为 Error * Array 等 的 
构造 函数 会 使 用 ECMAScript 6 的 new.target 来 调整 它们 的 原型 链 ; 然而 ， 在 
ee eee 
默认 情况 下 ， 其 它 低级 别 的 编译 器 遍 存在 这 个 限制 。 


示例 


针对 如 下 的 子 类 : 


class FooError extends Error { 
constructor(m: string) { 
super(m); 
} 
sayHello() { 
return "hello " + this.message; 


ass 
Ry 
xal 


He 


e 由 这 个 子 类 构造 出 来 的 对 象 上 的 方法 可 能 为 undefined ， 因 此 调 
用 sayHello 会 引发 错误 。 
e instanceof BAN A > 因此 (new FooError()) 


instanceof FooError 会 返回 false 。 


推荐 
做 为 一 个 推荐 ， 你 可 以 在 任何 super(...) 调用 后 立即 手动 地 调整 原型 。 


class FooError extends Error { 
constructor(m: string) { 
super (m); 


// Set the prototype explicitly. 
Object.setPrototypeOf(this, FooError.prototype); 


sayHello() { 
return "hello " + this.message; 


但 是 ， 任 何 FooError 的 子 类 也 必须 要 手动 地 设置 原型 。 对 于 那些 不 支 

持 Object.setPrototypeOf 的 运行 时 环境 ， 你 可 以 使 用 proto  。 

不 盏 的 是 ， 这 些 变通 方法 在 [E10 及 其 之 前 的 版 本 .aspx) 你 可 以 手动 地 将 方法 从 原型 
上 拷贝 到 实例 上 (比如 从 FooError.prototype 到 this ) ， 但 是 原型 链 却 是 无 
法 修复 的 。 


const 变量 和 readonly 属性 会 默认 地 推断 成 字 
面 类 型 
默认 情况 下 ， const 声明 和 readonly 属性 不 会 被 推断 成 字符 串 ， 数 字 ， 布 尔 和 


枚 举 字面 量 类 型 。 这 意味 着 你 的 变量 /属性 可 能 具有 比 之 前 更 细 的 类 型 。 这 将 体现 在 
4H] === fe l== AY AT e 


示例 


const DEBUG = true; // ##A true 类 型 ， 


ZW A boolean 类 型 








if (DEBUG === false) { // 错误 : 操作 符 '===' 不 能 应 用 于 'true' 和 'false' 

} 
‘| m EN uj 
推荐 


针对 故意 要 求 更 加 宽泛 类 型 的 情况 下 ， 将 类 型 转换 成 基础 类 型 : 


const DEBUG = <boolean>true; // ^boolean' 


xt BA FoR RIK KBAR Y FS 


类 型 


量 进 行 类 型 细 化 


当 泛 型 类 型 参数 具有 string ， number 或 boolean 约束 时 ， 会 被 推断 为 字符 
串 ， 数 字 和 布尔 字面 量 类 型 。 此 外 ， 如 果 字 面 量 类 型 有 相同 的 基础 类 型 
(如 string ) ， 当 没有 字面 量 类 型 做 为 推断 的 最 佳 超 类 型 时 这 个 规则 会 失效 。 


示例 


declare function push<T extends string>(.. 


zapgsc TID USE 


var x = push("A", "BU. NM // 推断 成 "A" | "p" | wen 在 TS vs M 


在 TS 2.0€7; string 


推荐 
在 调用 处 明确 指定 参数 类 型 : 


var x = pulsh<string>("A", B,C // xstring 


AA i f callback te KA 


参数 会 触发 implicit-any 错 误 


有 与 之 匹配 的 重 载 


在 之 前 编译 器 默默 地 赋予 callback (下 面 的 c ) 的 参数 一 个 any X8 °- MAX $ 
到 编译 器 如 何 解 析 重 载 的 函数 表达 式 。 从 TypeScript 2.1 开 始 ， 在 使 用 -- 
noImplicitAny 时 ， 这 会 触发 一 个 错误 。 


示例 


declare function func(callback: () => void): any; 
declare function func(callback: (arg: number) => void): any; 


func(c => { }); 
推荐 


删除 第 一 个 重 载 ， 因 为 它 实 在 没什么 意义 ; 上 面 的 函数 可 以 使 用 1 个 或 0 个 必须 参数 
调用 ， 因 为 函数 可 以 安全 地 忽略 额外 的 参数 。 


declare function func(callback: (arg: number) => void): any; 


func(c => ( }); 
func(() => { 1); 


或 者 ， 你 可 以 给 callback 的 参数 指定 一 个 明确 的 类 型 : 
func((c:number) => ( 3); 

过 号 操作 符 使 用 在 无 副作用 的 表达 式 里 时 会 被 标记 
Lat 

成 . 错 天 


大 多 数 情 况 下 ， 这 种 在 之 前 是 有 效 的 去 号 表达 式 现在 是 错误 。 


示例 


let x = Math.pow((3, 5)); // x = NaN, was meant to be “Math. pow( 


3, 5) 


// This code does not do what it appears to! 


let arr - []; 
switch(arr.length) ( 


case 0, 1: 
return 'zero or one'; 
default: 
return 'more than one'; 
} 
推荐 


--allowUnreachableCode 会 禁用 产生 警告 在 整个 编译 过 程 中 。 或 者 ， 你 可 以 使 
用 void 操作 符 来 镇 压 这 个 如 号 表达 式 错误 : 


0; 
(void a, 1); // no warning for ta 


let a 
let y 


标准 库 里 的 DOM APIS z 


e Node.firstChild > Node.lastChild > Node.nextSibling > Node.previousSibli 
ng，Node.parentElement 和 Node.parentNode 现 在 是 Node | null 而 


非 Node 。 
查看 #11113 了 解 详细 信息 。 


推荐 明确 检查 null 或 使 用 ! 断言 操作 符 (比如 node.lastChild! ) » 


TypeScript 2.0 


完整 的 破坏 性 改动 列表 请 到 这 里 查看 :breaking change issues. 


It BAR RIK AH) AIR EE AAT RAL att 
(narrowing) 


>- 
o 


类 型 细 化 不 会 在 函数 ， 类 和 |ambda 表 达 式 上 进 


例子 
var x: number | string; 


if (typeof x === "number") ( 
function inner(): number { 
return x; 77 Error, type of x is not narrowed, c. is numb 


er | string 


} 


var y: number = x; // OK, x is number 


编译 器 不 知道 回调 函数 什么 时 候 被 执行 。 考 虑 下 面 的 情况 : 


var X: number | string = "a"; 
if (typeof x === "string") f 
setTimeout(() => console.log(x.charAt(0)), 0); 


= 5» 

3 x.charAt() 被 调用 的 时 候 把 x 的 类 型 当 作 string 是 错误 的 ， 事 实 上 它 确实 
不 是 string 类 型 。 

推荐 


使 用 常量 代替 : 


const x: number | string = "a"; 


if (typeof x === "string") { 
setTimeout(() => console.log(x.charAt(0)), 0); 
} 
泛 型 参数 会 进行 类 型 细 化 
例子 


FUNcE Lon ogs T (obn em 
var t: T; 
if (obj instanceof RegExp) { 
t = obj; // RegExp is not assignable to T 
} 


推荐 可 以 把 局 部 变量 声明 为 特定 类 型 而 不 是 泛 型 参数 或 者 使 用 类 型 断言 。 
只 有 get 而 没有 set 的 存 取 器 会 被 自动 推断 
A readonly 属性 
例子 
class C { 


get x() { return 0; } 
j 


var c = new C(); 
c.x = 1; // Error Left-hand side is a readonly property 


推荐 


定义 一 个 不 对 属性 写 值 的 setter 。 


在 严格 模式 下 元 数 声 明 不 允许 出 现在 块 (block) 里 


在 严格 模式 下 这 已 经 是 一 个 运行 时 错误 。 从 TypeScript 2.0 开 始 ， 它 会 被 标记 为 编译 
Kr a iX o 


例子 


if( true ) { 
function foo() {} 


export = foo; 


推荐 
使 用 函数 表达 式 代替 : 


ar( true ) f 
const foo = function() {} 


TemplateStringsArray 现 是 是 不 可 变 的 


a cas Had M Aq 这 个 对 象 
带 有 一 个 raw 属性 (同样 是 不 可 变 的 ) © TypeScript 把 这 个 对 象 命 
为 TemplateStringsArray ° 


便利 的 是 ， TemplateStringsArray 可 以 赋值 给 Array<string> ， 因 此 你 可 以 
利用 这 个 较 短 的 类 型 来 使 用 标签 参数 : 


function myTemplateTag(strs: string[]) { 


// 
"ey, 1.a 


然而 ， 在 TypeScript 2.0 * 4&4 readonly 修饰 符 表示 这 些 对 象 是 不 可 变 的 。 这 
样 的 话 ， TemplatestringsArray 就 变 成 了 不 可 变 的 ， 并 且 不 再 可 以 赋值 


给 string[] 。 


推荐 


直接 使 用 TemplateStringsArray (或 者 使 用 ReadonlyArray<string> ) ° 


TypeScript 1.8 
完整 的 破坏 性 改动 列表 请 到 这 里 查看 :breaking change issues ° 


现在 生成 模块 代码 时 会 带 有 "use strict"; X 


在 ES6 模 式 下 模块 总 是 在 严格 模式 下 解析 ， 对 于 生成 目标 为 非 ES6 的 却 不 是 这 样 。 
从 TypeScript 1.8 开 始 ， 生 成 的 模块 将 总 为 严格 模式 。 这 应 该 不 会 对 现 有 的 大 部 分 代 
码 产 生 影响 ， 因 为 TypeScript 把 大 多 数 因为 严格 模式 而 产生 的 错误 当做 编译 时 错 

误 ， 但 还 是 有 一 些 在 运行 时 才 发 生 错 误 的 TypeScript 代 码 ， 比 如 赋值 给 Nan ， 现 在 
将 会 直接 报错 。 你 可 以 参考 MDN Article 学 习 关 于 严格 模式 与 非 严 格 模式 的 区 别 。 


若 想 禁 用 这 个 行为 ， 在 命令 行 里 传 --normplicitUsestrict 选项 或 在 
tsconfig.json 文 件 里 指定 。 


从 模块 里 导出 非 局 部 名 称 
依据 ES6/ES2015 规 范 ， 从 模块 里 导出 非 局 部 名 称 将 会 报错 。 


例子 


export { Promise }; // Error 


推荐 
在 导出 之 前 ， 使 用 局 部 变量 声明 捕获 那个 全 局 名 称 。 


const localPromise = Promise; 
export { localPromise as Promise }; 


默认 启用 代码 可 达 性 (Reachability) 检查 
TypeScript 1.8 里 ， 我 们 添加 了 一 些 可 达 性 检查 来 阻止 一 些 种 类 的 错误 。 特 别 是 : 


1. 检查 代码 的 可 达 性 (默认 启用 ， 可 以 通过 allowUnreachableCode 编译 器 选 


function testi() { 


return 1; 

return 2; // error here 
} 
function test2(x) t 

if (x) { 

return 1; 
} 
else { 


throw new Error("NYI") 


} 


var y = 1; // error here 


2. 检查 标签 是 否 被 使 用 (默认 启用 ， 可 以 通过 allowUnusedLabels 编译 器 选项 


$m) 


l: // error will be reported - label ‘1 is unused 
while (true) { 


j 
(x) => { x:x ) // error will be reported - label x is unus 
ed 

3. 检查 是 否 函 数 里 所 有 带 有 返回 值 类 型 注解 的 代码 路 径 都 返回 了 值 〈 软 认 忆 用 ， 


«3| 


是 否 
以 通过 noImplicitReturns 编译 器 选项 禁用 ) 


// error will be reported since function does not return any 
thing explicitly when x is falsy. 
function test(x): number { 

if (x) return 10; 


4. 检查 控制 流 是 否 能 进 到 Switch 语句 的 case 里 〈 黑 认 禁 用 ， 可 以 通 
过 noFallthroughCasesInSwitch 编译 器 选项 启用 ) 。 注 意 没 有 语句 的 case 
不 会 被 检查 。 


switch(x) { 


casem 
Gase Ze 
return LT: 


} 
switch(x) { 
case 1: 
if (y) return 1; 
case 2: 
returnt2; 


如 果 你 看 到 了 这 些 错误 ， 但 是 你 认为 这 时 的 代码 是 合理 的 话 ， 你 可 以 通过 编译 选项 
来 阻止 报错 。 


--module 不 允许 与 --outFile 一 起 出 现 ， 除 非 --module 被 指 
定 为 amd 或 system 


之 前 使 用 模块 指定 这 两 个 的 时 候 ， 会 生成 空 的 out 文件 且 不 会 报错 。 


标准 库 里 的 DOM APIS z 


e ImageData.data 现 在 的 类 型 为 Uint8ClampedArray 而 不 是 number[] ° & 
看 #949 © 

e HTMLSelectElement .options 现 在 的 类 型 为 HTMLCollection 而 不 
是 HTMLSelectElement 。 查 看 #1558。 

e HTMLTableElement.createCaption > HTMLTableElement.createTBody > H 
TMLTableElement.createTFoot > HTMLTableElement.createTHead > HTM 
LTableElement.insertRow > HTMLTableSectionElement.insertRow 7» 
HTMLTableElement.insertRow 现 在 返回 HTMLTableRowElement 而 不 
是 HTMLElement 。 查 看 #3583。 

。HTMLTableRowElement.insertCell 现 在 返回 HTMLTableCellElement 而 不 
是 HTMLElement 查看 #3583。 

e。1IDBObjectStore.createlndex 和 IDBDatabase.createlndex 第 二 个 参数 类 型 
为 IDBObjectStoreParameters 而 不 是 any 。 查 看 #5932。 

e DataTransferltemList.ltem 返 回 值 类 型 变 为 DataTransferItem 而 不 


x File 。 查 看 #6106。 
e Window.open 返 回 值 类 型 变 为 window 而 不 是 any 
e WeakMap.clear 被 移 除 。 查 看 #6500 ° 


在 super-call 之 前 不 允许 使 用 this 


ES6 不 允许 在 构造 函数 声明 里 访问 this ° 


比如 : 
class B { 
constructor(that?: any) {} 
} 


class C extends B { 
constructor() { 
super(this); // error; 


class D extends B ( 
private | propi: number; 
constructor() { 
this. propi = 10; // error 
super(); 


。 查 看 #6418。 


TypeScript 1.7 
完整 的 破坏 性 改动 列表 请 到 这 里 查看 :breaking change issues ° 


从 this 中 推断 类 型 发 生 了 变化 


在 类 里 ， this 值 的 类 型 将 被 推断 成 this 类 型 。 这 意味 着 随后 使 用 原始 类 型 赋 
值 时 可 能 会 发 生 错 误 。 


例子 : 


class Fighter { 
/** @returns the winner of the fight. */ 
fight(opponent: Fighter) { 
let theVeryBest = this; 
if (Math.rand() (Sus 
theVeryBest - opponent; // error 


^ 


j 
return theVeryBest 
j 
} 
推荐 : 
添加 类 型 注解 : 


class Fighter { 
/** @returns the winner of the fight. */ 
fight(opponent: Fighter) { 
let theVeryBest: Fighter = this; 
if (Math.rand() < 0.5) { 
theVeryBest - opponent; // no error 


j 


return theVeryBest 


类 成 员 修饰 符 后 面 会 自动 插入 分 号 


关键 字 abstract * public» protected 和 private ECMAScript 3 里 的 保留 关 
键 字 并 适用 于 自动 插入 分 号 机 制 。 之 前 ， 在 这 些 关键 字 出 现 的 行 尾 ，TypeScript 是 
不 会 插入 分 号 的 。 现在， 这 已 经 被 改正 了 ， 在 上 例 中 abstract class D 不 再 能 
够 正确 地 继承 C 了 ， 而 是 声明 了 一 个 m 方法 和 一 个 额外 的 属性 abstract 。 


注意 ， async 和 declare 已 经 能 够 正确 自动 播 入 分 号 了 。 


例子 : 


abstract class C { 
abstract m(): number; 


} 
abstract class D extends C { 
abstract 
m(): number; 
} 
推荐 : 
在 定义 类 成 员 时 删除 关键 字 后 面 的 换行 。 通 常 来 讲 ， 要 避免 依赖 于 自动 插入 分 号 机 


制 。 


TypeScript 1.6 
完整 的 破坏 性 改动 列表 请 到 这 里 查看 :breaking change issues ° 


严格 的 对 象 字 面 量 赋值 检查 


当 在 给 变量 赋值 或 给 非 空 类 型 的 参数 赋值 时 ， 如 果 对 象 字面 量 里 指定 的 某 属 性 不 存 
在 于 目标 类 型 中 时 会 得 到 一 个 错误 。 


你 可 以 通过 使 用 --suppressExcessPropertyErrors 编 译 器 选项 来 禁用 这 个 新 的 严格 


例子 : 


var X: { foo: number }; 
= ( foo: 1, baz: 2 }; // Error, excess property “baz” 


var y: { foo: number, bar?: number }; 
= (foo: 1, baz: 2 }; // Error, excess or misspelled property 
‘baz 


推荐 
避免 此 错误 ， 不 同情 况 下 有 不 同 的 补救 方法 : 
如 果 目 标 类 型 接收 额外 的 属性 ， 可 以 增加 一 个 索引 : 


var x= { foo: number, [x: string]: any *; 
= { foo: 1, baz: 2 }; // OK, baz matched by index signature 


如 果 原 始 类 型 是 一 组 相关 联 的 美 型 ， 使 用 联合 类 型 明确 指定 它们 的 类 型 而 不 是 仅 指 
定 一 个 基本 类 型 。 


let animalList: (Dog | Cat | Turkey)[] = [ /7 use union type 
instead of Animal 

(name: "Milo", meow: true }, 

{name: "Pepper", bark: true}, 

{name: "koko", gobble: true} 


1; 
还 有 可 以 明确 地 转换 到 目标 类 型 以 避免 此 错误 : 


interface Foo { 
foo: number; 


} 


interface FooBar { 
foo: number; 
bar: number; 


} 
var y: Foo; 
y = <FooBar>{ foo: 1, bar: 2 }; 


CommonJS 的 模块 解析 不 再 假设 路 径 为 相对 的 


之 前 ， 对 于 one.ts 和 two.ts 文件 ， 如 果 它 们 在 相同 目录 里 ， 那 么 
在 two.ts 里 面 导 入 "one" 时 是 相对 于 one.ts 的 路 径 的 。 


TypeScript 1.6 在 编译 CommonJS 时 ， "one" 不 再 等 同 于 "./one"。 取 而 代 之 的 是 会 
相对 于 合适 的 node modules 文件 夹 进行 查找 ， 与 Node.js 在 运行 时 解析 模块 相 
似 。 更 多 详情 ， 阅 读 the issue that describes the resolution algorithm 。 


例子 : 


./one.ts 


export function f() { 
return ror 


./two.ts 


import { f as g } from "one"; 


推荐 : 
修改 所 有 计划 之 外 的 非 相 对 的 导入 。 


./one.ts 


export function f() { 
return 107 


./two.ts 
import { f as g } from "./one"; 


2, 


将 --moduleResolution 编译 器 选项 设置 为 classic ° 


兄 数 和 类 声明 为 默认 导出 时 不 再 能 够 与 在 意义 上 有 交 又 的 同名 实 
体 进 行 合并 


在 同一 空间 内 默认 导出 声明 的 名 字 与 空间 内 一 实体 名 相同 时 会 得 到 一 个 错误 ; 比 
如 ， 


export default function foo() { 
j 


namespace foo ( 
var x - 100; 


和 


export default class Foo { 
a: number; 


interface Foo { 
be string, 


两 者 都 会 报错 。 


然而 ， 在 下 面 的 例子 里 合并 是 被 允许 的 ， 因 为 命名 空间 并 不 具备 做 为 值 的 意义 : 


export default class Foo { 


} 


namespace Foo { 


} 


推荐 : 
为 默认 导出 声明 本 地 变量 并 使 用 单独 的 export default 784 : 


class Foo { 
a: number; 


interface foo { 
Dees ir ind 


export default Foo; 


更 多 详情 ， 请 阅读 the originating issue ° 


模块 体 以 严格 模式 解析 


按照 ES6 规 范 ， 模 块 体现 在 以 严格 模式 进行 解析 。 行 为 将 相当 于 在 模块 作用 域 顶 端 
定义 了 "use strict" ; 它 包 括 限 制 了 把 arguments 和 eval 做 为 变量 名 或 参 
数 名 的 使 用 ， 把 未 来 保留 字 做 为 变量 或 参数 使 用 ， 人 和 八进制 数字 字面 量 的 使 用 等 。 
标准 库 里 DOM API 的 改动 


e MessageEvent/»ProgressEvent/ i& £i Zt di E 1% AR ; 查看 issue #4295 。 
e ImageData 构 造 函 数 希 望 传 入 参数 ; 查看 jssue #4220 © 
e File 构 造 函 数 希 望 传 入 参数 ; 查看 issue #3999 © 

系统 模块 输出 使 用 批量 导出 


编译 器 以 系统 模块 的 格式 使 用 新 的 _export 函数 批量 导出 的 变 体 ， 它 接收 任何 包 
含 键 值 对 的 对 象 做 为 参数 而 不 是 key, value » 


模块 加 载 器 需要 升级 到 v0.17.1 或 更 高 。 


npm & 49 .js 内 EM bin' 4 2 F "lib' 

TypeScript 的 npm 包 入 口 位 置 从 bin 移动 到 了 lib ， 以 

防 '"node_modules/typescript/bin/typescript.js' 通 过 IIS 访问 的 时 候 造 成 阻塞 
( bin 默认 是 隐藏 段 因此 |IS 会 阻止 访问 这 个 文件 夹 ) 。 


TypeScript 的 npm 包 不 会 默认 全 局 安装 


TypeScript 1.6 从 package.json 里 移 除 了 preferGlobal 标记 。 如 果 你 依赖 于 这 种 
行为 ， 请 使 用 npm install -g typescript 。 


装饰 器 做 为 调用 表达 式 进行 检查 


从 1.6 开 始 ， 装 饰 器 类 型 检查 更 准确 了 ; 编译 器 会 将 装饰 器 表达 式 做 为 以 被 装饰 的 实 
体 做 为 参数 的 调用 表达 式 来 进行 检查 。 这 可 能 会 造成 以 前 的 代码 报错 。 


TypeScript 1.5 
整 的 破坏 性 改动 列表 请 到 这 里 查看 :breaking change issues » 


不 允许 在 葡 头 函数 里 引用 arguments 


这 是 为 了 遵循 ES6 箭 头 函 数 的 语义 。 之 前 箭头 函数 里 的 arguments 会 绑 定 到 箭头 
函数 的 参数 。 参 照 ES6 规 范 草 稿 9.2.12， 箭 头 函 数 不 存在 arguments HR ° 从 
TypeScript 1.5 开 始 ， 在 箭头 函数 里 使 用 arguments 会 被 标记 成 错误 以 确保 你 的 代 
码 转 成 ES6 时 没 语义 上 的 错误 。 


例子 : 


hUREC ELON EAO 
return () => arguments; // Error: The 'arguments' object can 


not be referenced in an arrow function. 


} 
推荐 : 


// 1. 使 用 带 名 字 的 剩余 参数 
quc tron) 
return (...args) => { args; ) 


// 2. 使 用 函数 表达 式 
function f() { 
return function(){ arguments; } 


内 联 枚 举 引 用 的 改动 


对 于 正常 的 枚 举 ， 在 1.5 之 前 ， 编 译 器 仅 会 内 联 常 量 成 员 ， 且 成 员 仅 在 使 用 字面 量 初 
始 化 时 才 被 当做 是 常量 。 这 在 判断 检举 值 是 使 用 字面 量 初始 化 还 是 表达 式 时 会 行为 
不 一 致 。 从 TypeScript 1.5 开 始 ， 所 有 非 const 枚 举 成 员 都 不 会 被 内 联 。 


例子 : 


var x = E.a; // previously inlined as "var x = 1; /*E.a*/" 


推荐 : 在 枚 举 声 明 里 添加 const 修饰 符 来 确保 它 总 是 被 内 联 。 更 多 信息 ， 查 
看 #2183 ° 
上 下 文 的 类 型 将 作用 于 super 和 括号 表达 式 


在 1.5 之 前 ， 上 下 文 的 类 型 不 会 作用 于 括号 表达 式 内 部 。 这 就 要 求 做 显示 的 类 型 转 
换 ， 尤 其 是 在 必须 使 用 括号 来 进行 表达 式 转 换 的 场合 。 


在 下 面 的 例子 里 ，m 具有 上 下 文 的 类 型 ， 它 在 之 前 的 版 本 里 是 没有 的 。 


var x: SomeType = (n) => ((m) => q); 
t ? (m => m.length) : undefined; 


var y: SomeType 


class C extends CBase<string> ( 
constructor() { 


super ({ 
method(m) { return m.length; } 


3); 


更 多 信息 ， 查 看 #1425 和 #920。 


DOM 接 口 的 改动 


TypeScript 1.5 改 进 了 lib.d.ts 库 里 的 DOM 类 型 。 这 是 自 TypeScript 1.0 以 来 第 
一 次 大 的 改动 ; 为 了 拥抱 标准 DOM 规 范 ， 很 多 特定 于 IE 的 定义 被 移 除 了 ， 同 时 添加 
了 新 的 类 型 如 Web Audio 和 触摸 事件 。 


变通 方案 : 


你 可 以 使 用 上 昌 的 lib.d.ts 配合 新 版 本 的 编译 器 。 你 需要 在 你 的 工程 里 引入 之 前 版 
本 的 一 个 拷贝 。 这 里 是 本 次 改动 之 前 的 lib.d.ts 文 件 (TypeScript 1.5-alpha) ° 


变动 列表 : 


e 属性 selection 从 Document 类 型 上 移 除 

e 属性 clipboardData 从 window 类 型 上 移 除 

e 删除 接口 MSEventAttachmentTarget 

e & 
性 onresize * disabled ， uniqueID ， removeNode ， fireEvent ° 
currentStyle ， runtimeStyle 从 HTMLElement 类 型 上 移 除 

e 属性 url 从 Event 类 型 上 移 除 

e 属性 execScript * navigate ， item 从 Window 类 型 上 移 除 

e & 
性 documentMode * parentWindow * createEventObject 从 Document 
类 型 上 移 除 

e 属性 parentwindow 从 HTMLDocument 类 型 上 移 除 

e 属性 setCapture 被 完全 移 除 

e 属性 releaseCapture 被 完全 移 除 

e & 
性 setAttribute * styleFloat * pixelLeft 从 CSSStyleDeclaration 
类 型 上 移 除 

e 属性 selectorText 从 CSSRule 类 型 上 移 除 

e CSSStyleSheet.rules 现在 是 CSSRuleList 类 型 ， 而 非 MSCSSRuleList 

e documentElement 现在 是 Element 类 型 ， 而 非 HTMLElement 

e Event 具有 一 个 新 的 必需 属性 returnvalue 

e Node 具有 一 个 新 的 必需 属性 baseURI 

e Element 具有 一 个 新 的 必需 属性 classList 

e Location 具有 一 个 新 的 必需 属性 origin 

e & 
性 MSPOINTER TYPE MOUSE °’ MSPOINTER_TYPE_TOUCH 从 MSPointerEvent 
类 型 上 移 除 

e CSSStyleRule 具有 一 个 新 的 必需 属性 readonly 

e 属性 execUnsafeLocalFunction 从 MSApp 类 型 上 移 除 

e 全 局 方法 toStaticHTML 被 移 除 

e HTMLCanvasElement.getContext 现在 返回 CanvasRenderingContext2D | 
WebGLRender ingContex 


e 移 除 扩展 类 型 Dataview > Weakmap * Map ， Set 

e XMLHttpRequest.send 具有 两 个 重 载 send(data?: Document): 
void; 和 send(data?: String): void; 

e window.orientation 现在 是 string 类 型 ， 而 非 number 

e 特定 于 |E 的 attachEvent 和 detachEvent 从 window 上 移 除 


以 下 是 被 新 加 的 DOM 类 型 所 部 分 或 全 部 取代 的 代码 库 的 代表 : 


e DefinitelyTyped/auth0/authO.d.ts 

e DefinitelyTyped/gamepad/gamepad.d.ts 

e DefinitelyTyped/interactjs/interact.d.ts 
e DefinitelyTyped/webaudioapi/waa.d.ts 

e DefinitelyTyped/webcrypto/WebCrypto.d.ts 


更 多 信息 ， 查 看 完整 改动 。 


类 代码 体 将 以 严格 格式 解析 


按照 ES6 规 范 ， 类 代码 体现 在 以 严格 模式 进行 解析 。 行 为 将 相当 于 在 类 作用 域 顶端 
定义 了 "use strict" ; 它 包 括 限 制 了 把 arguments 和 eval 做 为 变量 名 或 参 
数 名 的 使 用 ， 把 未 来 保留 字 做 为 变量 或 参数 使 用 ， 人 和 八进制 数字 字面 量 的 使 用 等 。 


TypeScript 1.4 


完整 的 破坏 性 改动 列表 请 到 这 里 查看 :breaking change issues ° 


阅读 issue #868 以 了 解 更 多 关于 联合 类 型 的 破坏 性 改动 。 


多 个 最 佳 通用 类 型 候选 


当 有 多 个 最 佳 通用 类 型 可 用 时 ， 现 在 编译 器 会 做 出 选择 〈 依 据 编译 器 的 具体 实现 ) 
而 不 是 直接 使 用 第 一 个 。 


var a: { x: number; y?: number }; 
var b: { x: number; z?: number }; 


// 之 前 { x: number; z?: number; }[] 


// 现在 { x: number; y?: number; }[] 
var bs - [b, a]; 


这 会 在 多 种 情况 下 发 生 。 有 具有 一 组 共享 的 必需 属性 和 一 组 其 它 互 斥 的 (可 选 或 其 
T) 属性 ， 空 类 型 ， 兼 容 的 签名 类 型 ( 包括 泛 型 和 非 泛 型 签名 ， 当 类 型 参数 上 应 用 
f any 时 ) œ 


推荐 使 用 类 型 注解 指定 你 要 使 用 的 类 型 。 
var bs: { x: number; y?: number; z?: number }[] = [b, a]; 


泛 型 接口 


当 在 多 个 T 类 型 的 参数 上 使 用 了 不 同 的 类 型 时 会 得 到 一 个 错误 ， 就 算是 添加 约束 也 
A: 


declare function foo<T>(x: T, y:T): T; 


var r = foo(1, ""); // r used to be {}, now this is an error 


添加 约束 : 


interface Animal { x } 

interface Giraffe extends Animal { y } 

interface Elephant extends Animal { z } 

function f«T extends Animal>(x: T, y: T): T { return undefined; 
j 

var g: Giraffe; 

var e: Elephant; 

f(g, e); 


在 这 里 查看 详细 解释 。 


推荐 如 果 这 种 不 匹配 的 行为 是 故意 为 之 ， 那 么 明确 指定 类 型 参数 : 


var r = foo<{}>(1, ""); // Emulates 1.0 behavior 
foo<string|number>(1, ""); // Most useful 


var r 
var r = foo<any>(1, ""); // Easiest 
f<Animal>(g, e); 


或 重 写 函 数 定 义 指明 就 算 不 匹配 也 没 问 题 : 


declare function foo«T,U-(x* T, y:U): TIUS 
function f<T extends Animal, U extends Animal>(x: T, y: U): T|U 
{ return undefined; } 


泛 型 型 3 剩余 an 参数 
能 再 使 用 混杂 的 参数 类 型 : 


function makeArray<T>(...items: T[]): T[] { return items; } 
var r = makeArray(1, ""); // used to return {}[], now an error 


new Array(...) 也 一 样 


推荐 声明 向 后 兼容 的 签名 ， 如 果 1.0 的 行为 是 你 想 要 的 : 


function makeArray<T>(...items: T[]): T[]; 
function makeArray(...items: {}[]): GIL; 
function makeArray<T>(...items: T[]): T[] { return items; } 


带 类 型 参数 接口 的 重 载 解析 


var f10: <T>(x: T, b: () => (a: T) => void, y: T) => T; 
var r9 = f10('', () => (a => a.foo), 1); // r9 was any, now this 
is an error 


推荐 手动 指定 一 个 类 型 参数 


var r9 = f10<any>('', () => (a => a.foo), 1); 


类 声明 与 类 型 表达 式 以 严格 模式 解析 


ECMAScript 2015 语 言 规范 (ECMA-262 eth Edition) 指 明 ClassDeclaration 和 
ClassExpression 使 用 严格 模式 。 因此 ， 在 解析 类 声明 或 类 表达 式 时 将 使 用 额外 的 
限制 。 


例如 : 


class implements {} // Invalid: implements is a reserved word i 
n strict mode 
class C f 
foo(arguments: any) { // Invalid: "arguments" is not allow 
as a function argument 


var eval = 10; // Invalid: "eval" is not allowed as 
the left-hand-side expression 
arguments = []; // Invalid: arguments object is immu 
table 
} 
} 


关于 严格 模式 限制 的 完整 列表 ， 请 阅读 Annex C - The Strict Mode of ECMAScript 
of ECMA-262 6th Edition。 
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